创建快捷方式

快捷方式可帮助用户快速访问您的应用的某些部分，从而为他们呈现特定类型的内容。

您要如何以快捷方式来呈现内容取决于您的用例，以及快捷方式的上下文是属于应用驱动型还是用户驱动型。虽然静态快捷方式的上下文不会更改，而动态快捷方式的上下文会不断变化，但这两种情况下的上下文都由您的应用驱动。如果用户选择了希望应用以哪种方式（例如使用固定快捷方式）向其呈现内容，则此时的上下文是由用户定义的。以下场景展示了各类快捷方式的一些用例：

静态快捷方式最适合在用户与应用互动的整个生命周期内使用一致结构链接到内容的应用。由于大多数启动器一次只能显示四个快捷方式，因此静态快捷方式对常见 Activity 非常有用。例如，如果用户希望以特定的方式查看他们的日历或电子邮件，使用静态快捷方式可确保他们在执行日常任务时始终获得一致体验。
动态快捷方式用于应用中与上下文相关的操作。上下文相关快捷方式是专为用户在应用内执行的操作而定制的。例如，如果您构建的游戏允许用户在启动时从当前关卡开始，您需要经常更新该快捷方式。动态快捷方式允许游戏在每次用户通关后更新快捷方式。
固定快捷方式用于用户驱动的特定操作。例如，用户可能需要将特定网站固定到启动器。这很有用，因为它允许用户执行自定义操作，比如一步导航到网站，这比使用浏览器的默认实例速度更快。

创建静态快捷方式

静态快捷方式提供指向应用内常规操作的链接，这些操作在应用当前版本的生命周期内应保持一致。适合使用静态快捷方式的操作包括查看已发邮件、设置闹钟以及显示用户当天的锻炼活动。

如需创建静态快捷方式，请按顺序完成以下步骤：

在应用的清单文件 (AndroidManifest.xml) 中，找到 intent 过滤器设置为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 Activity。

向此 Activity 添加 <meta-data> 元素，该元素引用了定义应用快捷方式的资源文件：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.myapplication">
  <application ... >
    <activity android:name="Main">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      
      <meta-data android:name="android.app.shortcuts"
                 android:resource="@xml/shortcuts" /> 
    </activity>
  </application>
</manifest>

创建新的资源文件：res/xml/shortcuts.xml。

在这个新的资源文件中，添加 <shortcuts> 根元素，其中包含 <shortcut> 元素的列表。每个 <shortcut> 元素都包含有关一个静态快捷方式的信息，包括其图标、说明标签及其在应用内启动的 intent：

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/compose_icon"
    android:shortcutShortLabel="@string/compose_shortcut_short_label1"
    android:shortcutLongLabel="@string/compose_shortcut_long_label1"
    android:shortcutDisabledMessage="@string/compose_disabled_message1">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapplication"
      android:targetClass="com.example.myapplication.ComposeActivity" />
    <!-- If your shortcut is associated with multiple intents, include them
         here. The last intent in the list determines what the user sees when
         they launch this shortcut. -->
    <categories android:name="android.shortcut.conversation" />
    <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>

自定义属性值

以下列表介绍了静态快捷方式内的不同属性。您必须为 android:shortcutId 和 android:shortcutShortLabel 提供值。其他所有的值均为可选。

android:shortcutId

这是一个字符串字面量，表示 ShortcutManager 对象对其执行操作时的快捷方式。

注意：不能将此属性的值设置为资源字符串（例如 @string/foo）。

android:shortcutShortLabel

这是用于简短说明快捷方式用途的词组。请尽可能将快捷方式的“简短说明”的长度限制在 10 个字符以内。

如需了解详情，请参阅 setShortLabel()。

注意：此属性的值必须为资源字符串，例如 @string/shortcut_short_label。

android:shortcutLongLabel

这是用于详细说明快捷方式用途的词组。如果空间足够大，启动器会显示此值，而不是 android:shortcutShortLabel。请尽可能将快捷方式的“详细说明”的长度限制在 25 个字符以内。

如需了解详情，请参阅 setLongLabel()。

注意：此属性的值必须为资源字符串，例如 @string/shortcut_long_label。

android:shortcutDisabledMessage

这是当用户尝试启动已停用的快捷方式时出现在支持的启动器中的消息。此消息应向用户解释快捷方式现在停用的原因。如果 android:enabled 为 true，则此属性的值无效。

注意：此属性的值必须为资源字符串，例如 @string/shortcut_disabled_message。

android:enabled

这用于确定用户是否能够与支持的启动器中的快捷方式进行交互。 android:enabled 的默认值为 true。如果您将其设置为 false，则还应设置 android:shortcutDisabledMessage，用于说明停用该快捷方式的原因。如果您认为自己不需要提供此类消息，最简单的做法就是从 XML 文件中完全移除该快捷方式。

android:icon

这是启动器向用户显示快捷方式时所用的位图或自适应图标。此值可以是某个图片的路径，也可以是包含相应图片的资源文件。请尽可能使用自适应图标来提高性能和一致性。

注意：快捷方式图标不能包含色调。

配置内部元素

列出应用静态快捷方式的 XML 文件支持每个 <shortcut> 元素内的以下元素。您必须为您定义的每个静态快捷方式添加一个 intent 内部元素。

intent

这是系统在用户选择快捷方式时启动的操作。此 intent 必须为 android:action 属性提供一个值。

注意：这个 intent 元素不能包含字符串资源。

您可以为一个快捷方式提供多个 intent。如需了解详情，请参阅管理多个 intent 和 Activity、设置 intent 和 TaskStackBuilder 类参考文档。

categories

这用于为应用的快捷方式所执行的各类操作（如创建新的聊天消息）提供分组。

如需查看支持的快捷方式类别的列表，请参阅 ShortcutInfo 类参考文档。

capability-binding

声明与此快捷方式关联的功能。

在此示例中，快捷方式关联到一项为 CREATE_MESSAGE 声明的功能，该对象是与应用有关的 Action 内置 intent。这种独特的功能绑定使得用户可以结合使用语音指令与 Google 助理来调用此快捷方式。

创建动态快捷方式

动态快捷方式提供指向应用内特定的上下文相关操作的链接。这些操作可能会在应用的不同使用场景间发生变化，甚至会在应用运行时发生变化。适合使用动态快捷方式的用例包括致电特定人员、导航到特定位置，以及从用户的上一个存档点加载游戏。您也可以使用动态快捷方式打开一个对话。

ShortcutManagerCompat Jetpack 库是 ShortcutManager API 的帮助程序，可让您管理应用中的动态快捷方式。使用 ShortcutManagerCompat 库可减少样板代码，并确保各个 Android 版本的快捷方式保持一致。推送动态快捷方式也需要此库，以使这些快捷方式可以通过 Google 快捷方式集成库显示在 Google Surface（如 Google 助理）上。

ShorcutManagerCompat API 让您的应用可以通过动态快捷方式执行以下操作：

推送和更新：使用 pushDynamicShortcut() 发布和更新动态快捷方式。如果已经存在具有相同 ID 的动态快捷方式或固定快捷方式，那么每个可变快捷方式都会更新。
移除：使用 removeDynamicShortcuts() 移除一组动态快捷方式，或使用 removeAllDynamicShortcuts() 移除所有动态快捷方式。

如需详细了解如何对快捷方式执行操作，请参阅管理快捷方式和 ShortcutManagerCompat 参考文档。

以下示例代码段展示了如何创建动态快捷方式并将其与您的应用相关联：

Kotlin


val shortcut = ShortcutInfoCompat.Builder(context, "id1")
        .setShortLabel("Website")
        .setLongLabel("Open the website")
        .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
        .setIntent(Intent(Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")))
        .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

Java


ShortcutInfo shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(new Intent(Intent.ACTION_VIEW,
                   Uri.parse("https://www.mysite.example.com/")))
    .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

添加 Google 快捷方式集成库

Google 快捷方式集成库是一个可选的 Jetpack 库。借助这个库，您可以推送可在 Android Surface（如启动器）和 Google Surface（如 Google 助理）上显示的动态快捷方式，您的用户可以轻松发现您的快捷方式，以便快速访问应用中的特定内容或重放操作。例如，即时通讯应用可能会在用户发消息给“Alex”后推送该联系人的动态快捷方式。推送该动态快捷方式后，如果用户向 Google 助理发出指令“Ok Google, 通过 ExampleApp 给 Alex 发消息”，Google 助理就会启动 ExampleApp 并自动将其配置为给 Alex 发送消息。

通过此库推送的动态快捷方式不受对每台设备强制实施的快捷方式限制的约束，这使得您的应用可以在用户每次在您的应用中完成关联操作时推送一个快捷方式。以这种方式推送常用快捷方式，Google 就可以了解您用户的使用方式，并根据情境向他们推荐相关的快捷方式。例如，Google 助理可以从健身跟踪应用推送的快捷方式中了解到，用户通常每天早上都会去跑步，当用户早上拿起手机时，会主动推荐“开始跑步”快捷方式。

Google 快捷方式集成库本身不提供任何可寻址功能。将此库添加到您的应用后，Google Surface 便可以使用 ShortcutManagerCompat 提取您的应用推送的快捷方式。

如需在您的应用中使用此库，请按以下步骤操作：

更新 gradle.properties 文件以支持 AndroidX 库：


         android.useAndroidX=true
         # Automatically convert third-party libraries to use AndroidX
         android.enableJetifier=true

在 app/build.gradle 中，添加 Google 快捷方式集成库和 ShortcutManagerCompat 的依赖项：


         dependencies {
           implementation "androidx.core:core:1.6.0"
           implementation 'androidx.core:core-google-shortcuts:1.0.0'
           ...
         }

将库依赖项添加到 Android 项目后，您的应用就可以使用 ShortcutManagerCompat 的 pushDynamicShortcut() 方法推送可以在启动器和相关 Google Surface 上显示的动态快捷方式。

注意：我们建议您使用 pushDynamicShortcut 通过 Google 快捷方式集成库推送动态快捷方式。您的应用可以使用其他方法发布快捷方式，但如果达到最大快捷方式数限制，这些方法可能会失败。

创建固定快捷方式

在 Android 8.0（API 级别 26）及更高版本中，您可以创建固定快捷方式。与静态和动态快捷方式不同，固定快捷方式在受支持的启动器中显示为单独的图标。图 1 显示了这两类快捷方式之间的区别。

注意：当您尝试将快捷方式固定到受支持的启动器上时，用户会收到一个确认对话框，询问其是否允许固定该快捷方式。如果用户不允许固定该快捷方式，启动器会取消这一请求。

对比应用快捷方式与固定快捷方式的屏幕截图 — **图 1.** 应用快捷方式与固定快捷方式的外观

要将快捷方式固定到使用您的应用的受支持启动器上，请按顺序完成以下一系列步骤：

使用 isRequestPinShortcutSupported() 验证设备的默认启动器是否支持应用内固定快捷方式。
使用以下两种方式之一创建 ShortcutInfo 对象，具体采用哪种方式取决于是否已存在相应快捷方式：
1. 如果已存在相应快捷方式，请创建仅包含现有快捷方式 ID 的 ShortcutInfo 对象。系统会自动找到与该快捷方式相关的所有其他信息，并将其固定。
2. 如果您要固定原本不存在的新快捷方式，请创建包含新快捷方式 ID、intent 和简短标签的 ShortcutInfo 对象。
注意：由于系统会自动对固定快捷方式执行备份和恢复操作，因此这些快捷方式的 ID 应包含稳定的常量字符串或服务器端标识符，而不是在本地生成的可能对其他设备毫无意义的标识符。
尝试通过调用 requestPinShortcut() 将快捷方式固定到设备的启动器上。在此过程中，您可以传入一个 PendingIntent 对象，用于仅在快捷方式成功固定后通知您的应用。

注意：如果用户不允许将快捷方式固定到启动器上，您的应用就不会收到回调。

快捷方式固定后，您的应用可以使用 updateShortcuts() 方法更新其内容。如需了解详情，请参阅更新快捷方式。

以下代码段演示了如何创建固定快捷方式：

注意：ShortcutManager 类的实例必须使用带有参数 ShortcutManager.class 的 Context.getSystemService(Class) 或带有参数 Context.SHORTCUT_SERVICE 的 Context.getSystemService(String) 来获取。

Kotlin

val shortcutManager = getSystemService(ShortcutManager::class.java)

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    val pinnedShortcutCallbackIntent = shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

Java

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented a method called createShortcutResultIntent() that
    // returns a broadcast intent.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

    // Configure the intent so that your app's broadcast receiver gets
    // the callback successfully.For details, see PendingIntent.getBroadcast().
    PendingIntent successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0);

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

注意：另请参阅支持库 API、isRequestPinShortcutSupported() 和 requestPinShortcut()，它们适用于 Android 7.1（API 级别 25）及更低版本。支持库会回退至已弃用的 EXTRA_SHORTCUT_INTENT extra 以尝试固定流程。

创建自定义快捷方式 Activity

该自定义对话框 Activity 显示了提示“要将 Gmail 启动器图标添加到主屏幕吗？”。相应自定义选项为“不用了”和“添加图标”。 — **图 2.** 一个自定义应用快捷方式对话框 Activity 示例

您还可以创建一个专用 Activity 来帮助用户创建快捷方式，同时提供自定义选项和确认按钮。图 2 显示了 Gmail 应用中此类 Activity 的一个示例。

在应用的清单文件中，将 ACTION_CREATE_SHORTCUT 添加到 Activity 的 <intent-filter> 元素中。当用户尝试创建快捷方式时，此声明会设置以下行为：

系统启动应用的专用 Activity。
用户为快捷方式设置选项。
用户选择确认按钮。
应用使用 createShortcutResultIntent() 方法创建快捷方式。此方法会返回 Intent，应用会使用 setResult() 将其传回给之前正在执行的 Activity。
应用对用于创建自定义快捷方式的 Activity 调用 finish()。

同样，应用可以在安装后或首次启动时提示用户将固定快捷方式添加到主屏幕。此方法非常有效，因为它有助于用户在常规工作流程中创建快捷方式。

测试快捷方式

要测试应用的快捷方式，请在具有支持快捷方式的启动器的设备上安装应用。然后，执行下列操作：

长按应用的启动器图标，以查看您为应用定义的快捷方式。
点按并拖动快捷方式，将其固定到设备的启动器上。