创建快捷方式

快捷方式可帮助用户快速访问应用的各个部分，从而向用户提供特定类型的内容。

图 1. 应用快捷方式和固定快捷方式。

如何通过快捷方式提供内容取决于您的用例，以及快捷方式的上下文是由应用驱动还是由用户驱动。虽然静态快捷方式的上下文不会发生变化，而动态快捷方式的上下文会不断变化，但在这两种情况下，上下文都是由应用驱动的。如果用户选择应用向其提供内容的方式（例如通过固定快捷方式），则上下文由用户定义。以下场景介绍了每种快捷方式类型的几个用例：

• 静态快捷方式最适合在用户与应用互动的整个生命周期内使用一致的结构链接到内容的应用。由于大多数启动器一次只能显示四个快捷方式，因此静态快捷方式非常适合以一致的方式执行日常任务，例如，如果用户希望以特定方式查看其日历或电子邮件。
• 动态快捷方式用于应用中与上下文相关的操作。情境感知快捷方式是根据用户在应用中执行的操作量身定制的。例如，如果您构建了一款游戏，让用户在启动时从当前关卡开始，则需要经常更新快捷方式。使用动态快捷方式，您可以在用户每次通关时更新快捷方式。
• 固定快捷方式用于用户驱动的特定操作。例如，用户可能希望将特定网站固定到启动器。这很有用，因为用户可以执行自定义操作，例如一步导航到网站，比使用浏览器的默认实例更快。

创建静态快捷方式

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

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

1. 在应用的 AndroidManifest.xml 文件中，找到 intent 过滤器设为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 activity。

2. 向此 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>
   

   注意： 如果使用 activity-alias，请在 activity-alias 中定义元数据，而不是在使用 targetActivity 属性定位的 activity 中定义。

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

4. 在新的资源文件中，添加一个包含 <shortcut> 元素列表的 <shortcuts> 根元素。在每个 <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.Main" />
       <!-- 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>
   shortcuts.xml

自定义属性值

以下列表包含对静态快捷方式中不同属性的说明。为 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

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

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

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

categories

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

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

capability-binding

声明与快捷方式关联的 capability。

在前面的示例中，快捷方式关联到为 CREATE_MESSAGE（一种与应用有关的 Action 内置 intent）声明的功能。此功能绑定可让用户通过 Google 助理使用语音指令来调用快捷方式。

创建动态快捷方式

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

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

借助 ShortcutManagerCompat API，您的应用可以使用动态快捷方式执行以下操作：

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

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

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

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)
ShortcutsSnippets.kt

添加 Google 快捷方式集成库

Google 快捷方式集成库是一个可选的 Jetpack 库。借助该库，您可以推送可在 Android 界面（例如启动器）和 Google 界面上显示的动态快捷方式。使用此库可帮助用户发现您的快捷方式，以便快速访问特定内容或在应用中再次执行操作。

使用此库推送的动态快捷方式不受针对每台设备强制执行的快捷方式限制的约束。这样，您的应用就可以在用户每次通过应用完成相关操作时推送快捷方式。通过这种方式频繁推送快捷方式，可让 Google 了解用户的使用模式，并向他们推荐上下文相关的快捷方式。

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

Google Shortcuts Integration 库本身不提供任何可寻址功能。将此库添加到应用后，Google 产品界面便可接收应用使用 ShortcutManagerCompat 推送的快捷方式。

如需在应用中使用此库，请将 Google 快捷方式集成库和 ShortcutManagerCompat 的依赖项添加到 app/build.gradle 或 app/build.gradle.kts 文件中：

注意： 如需了解这些库的最新版本，请参阅 AndroidX Core 版本页面。

Kotlin

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

Groovy

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 显示了这两类快捷方式之间的区别。

注意： 当您尝试将快捷方式固定到受支持的启动器上时，用户会收到一个确认对话框，请求他们授予固定快捷方式的权限。如果用户不允许固定快捷方式，启动器会取消请求。

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

1. 使用 isRequestPinShortcutSupported() 验证设备的默认启动器是否支持应用内固定应用快捷方式。

2. 创建一个 ShortcutInfoCompat 对象，其中包含快捷方式的 ID、intent 和简短标签。如果快捷指令已存在，请使用现有快捷指令的 ID。系统会自动查找并固定与该快捷方式相关的所有其他信息。

   注意 ：ShortcutInfoCompat.Builder 需要简短标签和 intent，即使您使用的是现有快捷方式的 ID 也是如此。如果您不设置这些属性，build() 会抛出 IllegalArgumentException。
   注意 ：由于系统会自动对固定快捷方式执行备份和恢复操作，因此这些快捷方式的 ID 必须包含稳定的常量字符串或服务器端标识符，而不是在其他设备上可能没有意义的本地生成的标识符。

3. 通过调用 requestPinShortcut() 将快捷方式固定到设备的启动器。在此过程中，您可以传入一个 PendingIntent 对象，该对象仅在快捷方式成功固定时通知您的应用。

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

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

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

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .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 =
        ShortcutManagerCompat.createShortcutResultIntent(context, 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 */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}
ShortcutsSnippets.kt

注意： 在 Android 7.1（API 级别 25）及更低版本中，ShortcutManagerCompat 会回退到已废弃的 EXTRA_SHORTCUT_INTENT extra，以尝试执行固定流程。

创建自定义快捷方式 Activity

图 2. 自定义应用快捷方式对话框 activity 示例。

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

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

1. 系统会启动应用的专用 activity。
2. 用户为快捷方式设置选项。
3. 用户选择确认按钮。
4. 您的应用使用 createShortcutResultIntent() 方法创建快捷方式。此方法会返回一个 Intent，您的应用会使用 setResult() 将其传回之前执行的 activity。
5. 您的应用会对用于创建自定义快捷方式的 activity 调用 finish()。

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

测试快捷方式

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

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