创建快捷方式

快捷方式通过帮助用户快速访问应用的各个部分，为用户提供特定类型的内容。

An image showing the contrast between app shortcuts and pinned shortcuts — **图1.** 应用快捷方式和固定快捷方式。

你如何使用快捷方式传递内容取决于你的用例以及快捷方式的上下文是应用驱动的还是用户驱动的。虽然静态快捷方式的上下文不会改变，而动态快捷方式的上下文会不断改变，但在两种情况下，你的应用都会驱动上下文。在用户选择你的应用如何向他们传递内容的情况下，例如使用固定快捷方式，上下文由用户定义。以下场景描述了几种每种快捷方式类型的用例

静态快捷方式最适合那些在用户与应用交互的整个生命周期中使用一致的结构链接到内容的应用。 因为大多数启动器一次只显示四个快捷方式，所以静态快捷方式对于以一致的方式执行例行任务非常有用，例如，如果用户想以特定方式查看他们的日历或电子邮件。
动态快捷方式用于上下文相关的应用操作。 上下文相关的快捷方式是根据用户在应用中执行的操作量身定制的。例如，如果你构建一个允许用户从他们当前关卡开始的游戏，你需要频繁更新快捷方式。使用动态快捷方式，你可以每次用户通关时更新快捷方式。
固定快捷方式用于特定用户驱动操作。 例如，用户可能希望将特定网站固定到启动器。这非常有用，因为它允许用户执行自定义操作——例如一步一步地导航到网站，比使用浏览器的默认实例更快。

创建静态快捷方式

静态快捷方式提供指向应用内通用操作的链接，这些操作必须在应用当前版本的整个生命周期中保持一致。静态快捷方式的良好选择包括查看已发送的消息、设置闹钟以及显示用户当天的锻炼活动。

要创建静态快捷方式，请执行以下操作

在你的应用的 AndroidManifest.xml 文件中，找到其意图过滤器设置为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的活动。

向此活动添加一个 <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>

注意：如果使用 activity-alias，则在 activity-alias 中定义元数据，而不是使用 targetActivity 属性在其目标活动中定义。

创建一个名为 res/xml/shortcuts.xml 的新资源文件。

在新资源文件中，添加一个包含 <shortcut> 元素列表的 <shortcuts> 根元素。在每个 <shortcut> 元素中，包含有关静态快捷方式的信息，包括其图标、描述标签以及它在应用中启动的意图

  <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/shortcut_id。

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

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

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

你可以为单个快捷方式提供多个意图。有关详细信息，请参阅管理多个意图和活动、设置意图以及 TaskStackBuilder 类参考。

categories

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

有关支持的快捷方式类别的列表，请参阅 ShortcutInfo 类参考。

capability-binding

声明与快捷方式链接的功能。

在前面的示例中，快捷方式链接到为 CREATE_MESSAGE 声明的功能，这是一个应用操作内置意图。此功能绑定允许用户使用 Google 助理的语音命令来调用快捷方式。

创建动态快捷方式

动态快捷方式提供指向应用内特定、上下文相关的操作的链接。这些操作可能会在您使用应用的不同时间以及应用运行期间发生变化。动态快捷方式的良好用途包括呼叫特定人员、导航到特定位置以及从用户的最后保存点加载游戏。您还可以使用动态快捷方式来打开对话。

Jetpack 库 ShortcutManagerCompat 是 ShortcutManager API 的辅助工具，后者允许您管理应用中的动态快捷方式。使用 ShortcutManagerCompat 库可以减少样板代码，并帮助确保快捷方式在各个 Android 版本上都能一致地工作。此库对于推送动态快捷方式也是必需的，以便它们有资格出现在 Google 的界面（如 Google 助理）上，这需要使用 Google 快捷方式集成库。

ShortcutManagerCompat 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

ShortcutInfoCompat 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 界面（例如启动器）和 Google 界面（例如 Google 助理）上显示的动态快捷方式。使用此库可以帮助用户发现您的快捷方式，以便快速访问特定内容或在您的应用中重播操作。

例如，消息应用可能会在用户向名为“Alex”的联系人发送消息后推送该联系人的动态快捷方式。推送动态快捷方式后，如果用户询问 Google 助理，“嘿 Google，在 ExampleApp 上给 Alex 发消息”，Google 助理可以启动 ExampleApp 并自动将其配置为向 Alex 发送消息。

使用此库推送的动态快捷方式不受基于每个设备的快捷方式限制的约束。这允许您的应用在用户每次在您的应用中完成相关操作时推送快捷方式。以这种方式频繁推送快捷方式可以让 Google 了解用户的使用模式，并向他们建议上下文相关的快捷方式。

例如，Google 助理可以从您的健身追踪应用推送的快捷方式中了解到用户通常每天早上跑步，并在用户早上拿起手机时主动建议“开始跑步”快捷方式。

Google 快捷方式集成库本身不提供任何可寻址的功能。将此库添加到您的应用中，可以让 Google 界面接收您的应用使用 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 界面上显示的动态快捷方式。

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

创建固定快捷方式

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

要使用您的应用将快捷方式固定到支持的启动器，请完成以下步骤：

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

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

固定快捷方式后，您可以使用 updateShortcuts() 方法更新其内容。有关更多信息，请阅读更新快捷方式。

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

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

Kotlin

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

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements 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()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements 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 额外内容来尝试固定过程。

创建自定义快捷方式活动

An image showing the custom dialog activity that shows the prompt 'Do
you want to add the Gmail launcher icon to your home screen?' The custom
options are 'No thanks' and 'Add icon'. — **图 2.** 自定义应用快捷方式对话框活动的示例。

您还可以创建一个专门的活动来帮助用户创建快捷方式，其中包含自定义选项和确认按钮。图 2 显示了 Gmail 应用中此类活动的示例。

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

系统启动您的应用的专用活动。
用户设置快捷方式的选项。
用户选择确认按钮。
您的应用使用 createShortcutResultIntent() 方法创建快捷方式。此方法返回一个 Intent，您的应用使用 setResult() 将其转发回先前执行的活动。
您的应用对用于创建自定义快捷方式的活动调用 finish()。

类似地，您的应用可以在安装后或第一次启动应用时提示用户将固定快捷方式添加到主屏幕。这种方法很有效，因为它可以帮助用户在日常工作流程中创建快捷方式。

测试快捷方式

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

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