管理快捷方式

创建快捷方式后，您可能需要在应用的生命周期内对其进行管理。例如，您可能需要确定用户使用快捷方式完成特定操作的频率，从而优化应用。在另一种情况下，您可能会决定停用固定快捷方式，以防止应用执行过时或缺失的操作。对于在对话中引用的快捷方式，您可能需要跟踪使用情况，以提供有助于改进快捷方式排名的信号。

本页面介绍了这些方法以及其他几种管理快捷方式的常见方法。

快捷方式的行为

以下部分包含有关快捷方式行为的一般信息，包括可见性、显示顺序和排名。

快捷方式的可见性

重要提示： 所有快捷方式信息都存储在凭据加密存储空间中，因此在用户解锁设备之前，您的应用无法访问用户的快捷方式。

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

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

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

• 用户将其移除。
• 与该快捷方式关联的应用被卸载。
• 用户通过以下方式清除应用的数据：依次前往设置 > 应用和通知，选择相应应用，然后依次点按存储 > 清除存储空间。

分享目标是动态快捷方式的子集，会显示在 Android 分享表的直接分享行中。

图 1. Android Sharesheet。直接分享目标会显示在第一行，后面依次是经过排序的应用和应用列表。

快捷方式的显示顺序

当启动器显示应用的快捷方式时，这些快捷方式必须按以下顺序显示：

1. 静态快捷方式：其 isDeclaredInManifest() 方法返回 true 的快捷方式。
2. 动态快捷方式：其 ShortcutInfo.isDynamic() 方法返回 true 的快捷方式。

在每种快捷方式类型（静态和动态）中，快捷方式会根据 ShortcutInfo.getRank 按排名递增的顺序进行排序。Google 助理在确定要向用户显示的上下文快捷方式时，也会考虑快捷方式排名。

排名为连续的非负整数。静态快捷方式按照其在 shortcuts.xml 文件中出现的顺序从先到后进行排名。对于动态快捷方式，您可以在调用 updateShortcuts(Context, List)、addDynamicShortcuts(Context, List)、pushDynamicShortcut(Context, ShortcutInfoCompat) 或 setDynamicShortcuts(Context, List) 时更新现有快捷方式的排名。

分享目标的顺序取决于多种因素，包括过去的用户历史记录、新近度、频率、排名提示、应用使用情况以及与分享快捷方式关联的对话的优先级设置。使用 Sharing Shortcuts API 创建的分享目标优先于由 ChooserTargetService（在 Android 11 中已弃用）生成的分享目标。在 Android 12 及更高版本中，由已废弃的 ChooserTargetService 生成的分享目标将不再显示在分享表中。

大多数启动器最多显示四个快捷方式。对于已定义的静态快捷方式和动态快捷方式的任意组合，启动器最多可显示两个静态快捷方式和两个动态快捷方式。例如，如果您定义了 4 个静态快捷方式，并以编程方式创建了 3 个动态快捷方式，则启动器会显示前 2 个静态快捷方式和排名最高的 2 个动态快捷方式。

注意 ：排名会自动调整，因此每种类型的快捷方式（静态或动态）都有唯一的排名。例如，如果有三个动态快捷方式，其排名分别为 0、1 和 2，那么再添加一个排名为 1 的动态快捷方式，即表示请求将此快捷方式放在第二个位置。作为响应，之前排名为 1 和 2 的快捷方式的排名分别更改为 2 和 3。

管理多个 intent 和 Activity

如果您希望应用在用户激活快捷方式时执行多项操作，可以将其配置为触发连续 activity。您可以通过分配多个 intent、从一个 activity 启动另一个 activity 或设置 intent 标志来实现此目的，具体取决于快捷方式的类型。

从一个 Activity 启动另一个 Activity

静态快捷方式不能具有自定义 intent 标志。静态快捷方式的第一个 intent 始终设置了 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。这意味着，当您的应用正在运行时，如果启动静态快捷方式，应用中的所有现有 activity 都会被销毁。如果您不希望出现此行为，可以使用 trampoline activity（一种启动另一个 activity 的不可见 activity），方法是在启动块或 onCreate 中调用 finish，然后再设置 Compose 内容：

1. 在 AndroidManifest.xml file 中，将属性分配 android:taskAffinity="" 包含在跳板 activity 中。

2. 在快捷方式资源文件中，引用静态快捷方式中 intent 内的 trampoline activity。

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

设置 intent 标记

您可以使用任意一组 Intent 标志发布动态快捷方式。最好在快捷方式的 intent 中指定 Intent.FLAG_ACTIVITY_SINGLE_TOP 和 Intent.FLAG_ACTIVITY_CLEAR_TOP 的组合。这样可确保如果您的 ComponentActivity 已处于活跃状态，它会被带到前台并重复使用，而不会被销毁，从而使您的单 activity 架构能够通过 onNewIntent() 妥善处理快捷方式事件。

如需详细了解任务和 intent 标志，请参阅任务和返回堆栈。

更新快捷方式

每个应用的启动器图标最多可以包含的静态快捷方式和动态快捷方式总数等于 getMaxShortcutCountPerActivity 返回的值。应用可以创建的固定快捷方式数量没有限制。

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

请考虑以下示例，该示例假设 getMaxShortcutCountPerActivity 返回的值为 4：

1. 某聊天应用发布了四个动态快捷方式，分别代表四个最近的对话：c1、c2、c3 和 c4。
2. 用户固定了所有这四个快捷方式。
3. 之后，该用户又发起了 3 个对话：c5、c6 和 c7。发布者应用会重新发布其动态快捷方式。新的动态快捷方式列表为：c4、c5、c6 和 c7。

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

然后，用户总共可以访问 7 个链接到发布者应用中 activity 的快捷方式。这是因为总数包括快捷方式数量上限和 3 个固定快捷方式。

1. 应用可以使用 updateShortcuts(Context, List) 更新现有的 7 个快捷方式中的任何一个。例如，当聊天对象的图标发生变化时，您可能需要更新这组快捷方式。
2. 您可以使用 addDynamicShortcuts(Context, List) 和 setDynamicShortcuts(Context, List) 方法更新具有相同 ID 的现有快捷方式。不过，您无法使用它们来更新非动态的固定快捷方式，因为这两种方法会尝试将给定的快捷方式列表转换为动态快捷方式。

可推送以在 Google 助理等辅助应用上显示的快捷方式数量没有限制。使用 ShortcutManagerCompat Jetpack 库的 pushDynamicShortcut 方法创建和更新快捷方式，以便在辅助应用中使用。此外，请将 Google 快捷方式集成库添加到您的应用中，以便动态链接能够在 Google 助理中显示。

如需详细了解应用快捷方式指南（包括更新快捷方式），请参阅快捷方式最佳实践。

处理系统语言区域的变更

当应用收到指示系统语言区域发生更改的 Intent.ACTION_LOCALE_CHANGED 广播时，必须更新动态快捷方式和固定快捷方式。

跟踪快捷方式的使用情况

为了确定在哪些情况下显示静态和动态快捷方式，启动器会检查快捷方式的激活历史记录。对于静态快捷方式，您可以在发生以下任一事件时，通过调用 reportShortcutUsed 方法并向其传递快捷方式的 ID，来跟踪用户何时在应用内完成特定操作：

• 用户选择具有指定 ID 的快捷方式。
• 在应用内，用户手动完成与同一快捷方式对应的操作。

应用通过调用 pushDynamicShortcut 方法并在相关事件发生时向其传递快捷方式的 ID 来跟踪动态快捷方式的使用情况。 通过此方法推送动态快捷方式使用情况，可让 Google 助理等辅助应用向用户建议相关快捷方式。由于 pushDynamicShortcut 方法会在调用时报告使用情况，因此请勿针对相同的快捷方式调用 reportShortcutUsed 方法。

对于与对话相关的快捷方式，请务必跟踪传出和收到的消息的使用情况。如需了解详情，请参阅人员和对话最佳实践。

注意： 您需要使用 Google 快捷方式集成库，才能让应用推送的动态链接有资格显示在 Google 产品界面（例如 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" 属性分配，让用户在更换设备时对应用执行备份和恢复操作。如果您支持备份和恢复，请注意以下有关应用快捷方式的事项：

• 静态快捷方式会自动重新发布，但前提是用户在新设备上重新安装您的应用。
• 动态快捷方式不会备份，因此请在应用中添加逻辑，以便在用户于新设备上打开应用时重新发布这些快捷方式。
• 固定快捷方式会自动恢复到设备的启动器，但系统不会备份与固定快捷方式关联的图标。 因此，请将固定快捷方式的图片保存在应用中，以便在新设备上快速恢复。

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

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getShortcuts(this, ShortcutManagerCompat.FLAG_MATCH_PINNED).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}
ShortcutsSnippets.kt