应用快捷方式

创建快捷方式

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

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

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

创建静态快捷方式

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

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

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>
   

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

4. 在这个新的资源文件中，添加 <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 参考文档。

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

KotlinJava

ShortcutInfo shortcut = new ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(Icon.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 提取您的应用推送的快捷方式。

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

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

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

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

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

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

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

创建固定快捷方式

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

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

图 1. 应用快捷方式与固定快捷方式的外观

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

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

2. 使用以下两种方式之一创建 ShortcutInfo 对象，具体采用哪种方式取决于是否已存在相应快捷方式：

   1. 如果已存在相应快捷方式，请创建仅包含现有快捷方式 ID 的 ShortcutInfo 对象。系统会自动找到与该快捷方式相关的所有其他信息，并将其固定。
   2. 如果您要固定原本不存在的新快捷方式，请创建包含新快捷方式 ID、intent 和简短标签的 ShortcutInfo 对象。

   注意：由于系统会自动对固定快捷方式执行备份和恢复操作，因此这些快捷方式的 ID 应包含稳定的常量字符串或服务器端标识符，而不是在本地生成的可能对其他设备毫无意义的标识符。

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

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

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

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

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

KotlinJava

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

图 2. 一个自定义应用快捷方式对话框 Activity 示例

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

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

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

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

测试快捷方式

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

快捷方式的显示顺序

当启动器显示某个应用的快捷方式时，它们应按以下顺序排列：

在每类（静态和动态）快捷方式内，快捷方式按 ShortcutInfo.getRank() 返回的排名升序排列。在确定向用户显示的上下文快捷方式时，Google 助理还会考虑快捷方式排名。

排名为连续的非负整数。您可以在调用 updateShortcuts(Context, List)、 addDynamicShortcuts(Context, List) 或 setDynamicShortcuts(Context, List) 时更新现有快捷方式的排名。

注意：排名会自动调整，因此，每类（静态或动态）快捷方式都只有一种排名。例如，假设有三个排名分别为 0、1 和 2 的动态快捷方式，如果再添加另一个排名为 1 的动态快捷方式，则表示请求将此快捷方式置于第二位。作为响应，第三个和第四个快捷方式将进一步靠近快捷方式列表底部，其排名将分别变为 2 和 3。

管理多个 intent 和 Activity

如果您希望应用在用户启动某个快捷方式时执行多项操作，您可以将其配置为触发连续 Activity。为此，您可以分配多个 intent、从一个 Activity 启动另一个 Activity，或者设置 intent 标记，具体取决于快捷方式的类型。

分配多个 intent

使用 ShortcutInfoCompat.Builder 创建快捷方式时，您可以使用 setIntents() 代替 setIntent()。通过调用 setIntents()，您可以在用户选择某个快捷方式时在应用内启动多个 Activity，同时将列表中除最后一个 Activity 之外的所有 Activity 放到返回堆栈上。如果用户随后决定按下设备的返回按钮，他们将在应用中看到另一项 Activity，而不是返回设备的启动器。

注意：如果用户在选择某个快捷方式后按下返回键，您的应用会启动与快捷方式资源文件中列出的倒数第二个 intent 相对应的 Activity。此行为模式会在用户反复按下返回按钮时继续，直到用户清除快捷方式创建的返回堆栈为止。接下来，如果用户按下返回按钮，系统会使其返回到启动器。

从一个 Activity 启动另一个 Activity

静态快捷方式不能有自定义 intent 标记。 静态快捷方式的第一个 intent 始终设置有 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。这意味着，如果应用已在运行，则在静态快捷方式启动时，应用中的所有现有 Activity 都会被销毁。如果不希望出现这种行为，您可以使用 Trampoline Activity，或者使用一个先在 Activity.onCreate(Bundle) 中启动其他 Activity、而后调用 Activity.finish() 的不可见 Activity：

如需详细了解 Trampoline Activity，请参阅从一个 Activity 启动另一个 Activity。

设置 intent 标记

您可以使用任意一组 Intent 标记发布动态快捷方式。最好指定 Intent.FLAG_ACTIVITY_CLEAR_TASK 以及其他标记。否则，如果您在应用运行期间尝试启动其他任务，目标 Activity 可能不会显示。

要详细了解任务和 intent 标记，请参阅任务和返回堆栈指南。

更新快捷方式

每个应用的启动器图标最多只能包含 getMaxShortcutCountPerActivity() 个静态和动态快捷方式。不过，应用可以创建的固定快捷方式数量没有限制。

在动态快捷方式固定好以后，即使发布商将其作为动态快捷方式移除，该固定快捷方式仍然可见且可启动。这样，应用拥有的快捷方式可以超过 getMaxShortcutCountPerActivity() 个。

例如，假设 getMaxShortcutCountPerActivity() 为 4：

对可以推送到助理应用（例如 Google 助理）中进行显示的快捷方式数量没有限制。使用 ShortcutManagerCompat Jetpack 库的 pushDynamicShortcut() 方法创建和更新助理应用的快捷方式。此外，还必须在应用中添加 Google 快捷方式集成库，动态链接才能在 Google 助理上显示。

如需详细了解我们的应用快捷方式准则（包括如何更新快捷方式），请参阅最佳做法。

处理系统语言区域的变更

应用在收到 Intent.ACTION_LOCALE_CHANGED 广播（表明系统语言区域已更改）后，应更新动态和固定快捷方式。

跟踪快捷方式的使用情况

为了确定静态和动态快捷方式应在哪些情况下出现，启动器将检查快捷方式的启动记录。对于静态快捷方式，当发生以下任一事件时，可以通过调用 reportShortcutUsed() 方法并向其传递快捷方式的 ID 来跟踪用户何时在应用中完成特定操作：

当发生相关事件时，您的应用通过调用 pushDynamicShortcut() 方法并向其传递快捷方式的 ID 来跟踪动态快捷方式的使用情况。通过此方法推送动态快捷方式使用情况，可以让助理应用（如 Google 助理）向用户推荐相关的快捷方式。由于 pushDynamicShortcut() 方法会在被调用时报告使用情况，因此不应对同一快捷方式调用 reportShortcutUsed() 方法。

注意：需要使用 Google 快捷方式集成库，才能使您的应用推送的动态链接显示在 Google Surface（例如 Google 助理）上。将此库添加到应用中即表示您允许 Google 助理提取您的动态链接，并从 Google 助理应用中向用户推荐这些链接。

停用快捷方式

由于您的应用及其用户可以将快捷方式固定到设备的启动器上，因此这些固定快捷方式可能会引导用户执行应用中已过期或不存在的操作。为应对这种情况，您可以调用 disableShortcuts() 来停用不希望用户选择的快捷方式；该方法会从静态和动态快捷方式列表中移除指定的快捷方式，并停用这些快捷方式的所有固定副本。您还可以使用此方法的过载版本，它会接受 CharSequence 作为自定义错误消息。随后，当用户尝试启动任何已停用的快捷方式时，就会显示该错误消息。

注意：如果您在更新应用时移除了应用的某些静态快捷方式，系统会自动停用这些快捷方式。

调用频率限制

使用 setDynamicShortcuts()、 addDynamicShortcuts() 或 updateShortcuts() 方法时，请记住，您在后台应用（当前在前台没有任何 Activity 或服务的应用）中调用这些方法的次数可能有特定的上限。您可以调用这些方法的特定次数上限称为“调用频率限制”。此功能用于防止 ShortcutManagerCompat 过度使用设备资源。

启用调用频率限制后， isRateLimitingActive() 会返回 true。不过，在某些事件期间，系统会重置调用频率限制，因此，即使是后台应用也可以调用 ShortcutManager 方法，直到再次达到调用频率限制。这些事件包括：

如果您在开发或测试期间遇到调用频率限制，则可以在设备的“设置”中选择开发者选项 > 重置 ShortcutManager 调用频率限制，或者在 adb 中输入以下命令：

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

备份和恢复

通过在应用的清单文件中添加 android:allowBackup="true" 属性赋值，您可以允许用户在更换设备时对应用执行备份和恢复操作。如果您允许备份和恢复，请牢记有关应用快捷方式的以下注意事项：

以下代码段演示了如何以最佳方式恢复应用的动态快捷方式以及如何检查是否保留了应用的固定快捷方式：

KotlinJava

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Need to re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts have been restored. Use
                // updateShortcuts() to make sure they contain
                // up-to-date information.
            }
        }
    }
    // ...
}

其他资源

Android AppShortcuts 示例进一步说明了如何使用本页介绍的工作流程。

例如，如果您创建了导航到超市的快捷方式，那么在超市的名称发生更改但其位置保持不变的情况下更新快捷方式才比较合适。不过，如果用户开始在其他超市购物，则最好创建一个新的快捷方式。

发布应用时即检查动态快捷方式

当用户将数据恢复到新设备时，系统不会保留动态快捷方式。 因此，我们建议您在每次启动应用时检查 getDynamicShortcuts() 返回的对象数量，并根据需要重新发布动态快捷方式，如备份和恢复中的代码段所示。

• 长按应用的启动器图标，以查看您为应用定义的快捷方式。

• 管理快捷方式

  创建快捷方式后，您需要在应用生命周期内对其进行管理。例如，您可能需要确定用户使用您的快捷方式完成特定操作的频率，以此来优化应用。在其他情况下，您可能会决定停用某个固定快捷方式，以防止应用执行过时或缺失的操作。本指南将介绍这些方法以及其他几种管理快捷方式的常用方法。

  快捷方式的行为

  以下各个部分将介绍有关快捷方式行为的常规信息，包括可见性、显示顺序和排名。

  快捷方式的可见性

  安全方面的重要提示：所有快捷方式信息均存储在凭据加密存储空间中，因此您的应用只能在用户解锁设备之后访问用户的快捷方式。

  当用户执行特定手势或语音指令时，静态快捷方式和动态快捷方式会显示在支持的启动器或助理中。在支持的启动器上，让快捷方式显示出来的手势是长按应用的启动器图标，但其他启动器应用上实际适用的手势可能有所不同。借助 Google 助理，您可以在 Google 助理中显示快捷方式，也可以通过用户语音指令启动快捷方式。

  LauncherApps 类提供了多个供启动器应用访问快捷方式的 API。

  固定快捷方式显示在启动器中，因此它们始终可见。 只有在以下情况下，固定快捷方式才会从启动器中移除：

• 用户将其移除。
• 与该快捷方式关联的应用被卸载。
• 用户转至设置 > 应用和通知，选择一个应用并按下存储 > 清除存储空间，清除了应用的数据。
• 静态快捷方式：其 isDeclaredInManifest() 方法返回 true 的快捷方式。
• 动态快捷方式：其 ShortcutInfo.isDynamic() 方法返回 true 的快捷方式。
• 在 AndroidManifest.xml 文件中，Trampoline Activity 应包含属性分配 android:taskAffinity=""。
• 在快捷方式资源文件中，静态快捷方式内的 intent 应引用 Trampoline Activity。
• 聊天应用发布了四个动态快捷方式，分别表示 4 个最近的会话（c1、c2、c3 和 c4）。
• 用户固定了所有这四个快捷方式。

• 之后，用户启动了另外三个会话（c5、c6 和 c7），因此，发布商应用重新发布了动态快捷方式。新的动态快捷方式列表为：c4、c5、c6 和 c7。

  应用必须移除 c1、c2 和 c3，因为它不能显示四个以上的动态快捷方式。 不过，c1、c2 和 c3 仍然是用户可以访问和启动的固定快捷方式。

  用户现在总共可以访问七个快捷方式，它们都链接到发布商应用中的 Activity。这是因为总数中包含达到数量上限的快捷方式和 3 个固定快捷方式。

• 应用可使用 updateShortcuts(Context, List) 来更新现有七个快捷方式中的任何一个。例如，您可以在聊天对象的图标发生更改时更新这组快捷方式。
• addDynamicShortcuts(Context, List) 和 setDynamicShortcuts(Context, List) 方法还可用于更新具有相同 ID 的现有快捷方式。不过，它们无法用于更新非动态的固定快捷方式，因为这两种方法都会尝试将指定的快捷方式列表转换为动态快捷方式。
• 用户选择具有指定 ID 的快捷方式。
• 在应用内，用户手动完成与同一快捷方式对应的操作。
• 应用进入前台。
• 系统语言区域发生变化。
• 用户对通知执行内嵌回复操作。
• 静态快捷方式会自动重新发布，但这只发生在用户在新设备上重新安装您的应用后。
• 系统不会备份动态快捷方式，因此您必须在应用中添加相应的逻辑，以便在用户在新设备上打开应用时重新发布动态快捷方式。
• 固定快捷方式会自动恢复到设备的启动器，但系统不会备份与固定快捷方式关联的图标。因此，您应将固定快捷方式的图片保存在应用中，以便轻松将其恢复到新设备上。

• 使用快捷方式的最佳做法

  在设计和创建应用快捷方式时，请遵循以下准则：

  遵循设计准则

  为使您的应用的快捷方式在视觉上与系统应用的快捷方式保持一致，请遵循应用快捷方式设计准则。

  仅发布四个不同的快捷方式

  尽管 API 目前支持在任意指定时间为应用总计发布最多十五个静态和动态快捷方式，但我们建议您仅发布四个不同的快捷方式，以改善其在启动器中的视觉外观。

  除了在启动器上显示快捷方式之外，您还可以使用 Google 快捷方式集成库在 Google Surface（例如 Google 助理）上显示快捷方式。此库支持推送任意数量的动态快捷方式。如果您要使用此库推送大量快捷方式，我们建议您通过调用 setRank() 方法来设置在支持的启动器中应该显示的快捷方式“排名”。

  限制快捷方式说明的长度

  启动器中用来显示应用快捷方式的菜单空间有限。 请尽可能将快捷方式的“简短说明”的长度限制在 10 个字符以内，将“详细说明”的长度限制在 25 个字符以内。

  如需详细了解静态快捷方式的标签，请参阅自定义属性值。如需了解动态和固定快捷方式，请参阅有关 setLongLabel() 和 setShortLabel() 的参考文档。

  保留快捷方式和操作的使用记录

  对于您创建的每个快捷方式，请考虑用户可以通过哪些不同方式直接在应用内完成同一任务。请务必在每种情况下调用 reportShortcutUsed()，以便启动器准确记录用户执行快捷方式所表示的操作的频率。

  仅对含义未变的快捷方式执行更新

  更改动态快捷方式和固定快捷方式时，请仅在更改含义未变的快捷方式的信息时调用 updateShortcuts()。否则，您应该使用下列方法之一，具体取决于您要重新创建的快捷方式的类型：

• 动态快捷方式： pushDynamicShortcut()。
• 固定快捷方式： requestPinShortcut()。
• 点按并拖动快捷方式，将其固定到设备的启动器上。