创建快捷方式

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

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 助理的语音命令来调用快捷方式。

创建动态快捷方式

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

ShortcutManagerCompat Jetpack 库是 ShortcutManager API 的帮助程序，它允许您管理应用中的动态快捷方式。使用 ShortcutManagerCompat 库可以减少样板代码，并有助于确保快捷方式在 Android 版本之间一致地工作。此库对于推送动态快捷方式也是必需的，以便它们有资格出现在 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 表面（如 Assistant）上显示的动态快捷方式。使用此库可帮助用户发现您的快捷方式，以便快速访问特定内容或在您的应用中重放操作。

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

使用此库推送的动态快捷方式不受快捷方式限制（按设备强制执行）的影响。这使您的应用能够在用户在应用中完成相关操作时每次都推送快捷方式。通过这种方式频繁推送快捷方式，可以让 Google 了解用户的使用模式，并向他们建议相关的快捷方式。

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

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());
}

注意：另请参阅支持库 APIisRequestPinShortcutSupported()和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()。

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

测试快捷方式

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

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