App 快捷方式——管理快捷方式

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

注意：当用户选择快捷方式然后按后退键时，您的应用程序将启动与资源文件中列出的快捷方式倒数第二个 intent 相对应的 activity。重复按下后退按钮后，此行为模式继续，直到用户清除快捷方式创建的返回栈。当用户下一次按下后退按钮时，系统会将它们导航回启动器。

从另一个 activity 开启一个 activity

静态快捷方式不能具有自定义 intent flags。静态快捷方式的第一个意图始终设置为 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。这意味着，当应用程序已经运行时，启动静态快捷方式时，应用程序中的所有现有 activities 都将被销毁。如果不希望出现这种情况，可以使用 , trampoline activity，或者在 Activity.onCreate(Bundle)中启动另一个 activity 的不可见 activity，然后调用 Activity.finish()：

在 AndroidManifest.xml 文件中，trampoline activity 应该包含属性赋值 android:taskAffinity=""。
在快捷方式资源文件中，静态快捷方式中的 intent 应引用 trampoline activity。

有关 trampoline activities 的更多信息，请阅读 Start one activity from another。

设置 intent flags

可以使用任何 Intent flags 集发布动态快捷方式。您最好指定 Intent.FLAG_ACTIVITY_CLEAR_TASK 以及其他标志。否则，如果您在应用程序运行时尝试启动其他任务，则可能不会显示目标 activity。

要了解有关任务和 intent flags 的更多信息，请阅读任务和返回栈指南。

更新快捷方式

每个应用程序的启动器图标最多可以包含 getMaxShortcutCountPerActivity() 个静态和动态快捷方式组合。但是，应用程序可以创建的固定快捷方式数量没有限制。

固定动态快捷方式时，即使发布者将其作为动态快捷方式删除，固定的快捷方式仍然可见并可启动。这允许应用程序拥有超过 getMaxShortcutCountPerActivity() 个快捷方式。

例如，假设 getMaxShortcutCountPerActivity() 为四：

聊天应用程序发布四个动态快捷方式，表示最近的四个对话 (c1, c2, c3, c4)。
用户固定所有四个快捷方式。
之后，用户又启动了三个额外的对话（c5，c6 和 c7），因此发布者应用程序会重新发布其动态快捷方式。新的动态快捷列表是：c4，c5，c6，c7。

该应用程序必须删除 c1，c2 和 c3，因为它无法显示四个以上的动态快捷方式。但是，c1，c2 和 c3 仍然是用户可以访问和启动的固定快捷方式。

用户现在可以访问总共七个链接到发布者应用程序中的 activities 的快捷方式。这是因为总数包括最大快捷方式数和三个固定快捷方式。
应用程序可以使用 updateShortcuts(List) 来更新现有七个快捷方式中的任何一个。例如，当聊天伙伴的图标发生变化时，您可能会更新这组快捷方式。
addDynamicShortcuts(List) 和 setDynamicShortcuts(List) 方法也可用于更新具有相同ID的现有快捷方式。但是，它们不能用于更新非动态固定快捷方式，因为这两种方法会尝试将给定的快捷方式列表转换为动态快捷方式。

要详细了解我们的应用程序快捷方式指南，包括更新快捷方式，请阅读最佳实践。

处理系统区域设置更改

应用程序在收到 Intent.ACTION_LOCALE_CHANGED 广播时应更新动态和固定快捷方式，表示系统区域设置已更改。

跟踪快捷方式用法

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

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

禁用快捷方式

由于应用程序及其用户可以将快捷方式固定到设备的启动器，因此这些固定快捷方式可能会引导用户执行应用程序中过期或不再存在的操作。要管理这种情况，您可以通过调用 disableShortcuts()来禁用不希望用户选择的快捷方式，这将从静态和动态快捷方式列表中删除指定的快捷方式，并禁用这些快捷方式的任何固定副本。您还可以使用此方法的另一个重载版本，它接受一个字符序列作为自定义错误消息。当用户试图启动任何已禁用的快捷方式时，就会出现该错误消息。

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

速率限制

使用 setDynamicShortcuts()，addDynamicShortcuts()或updateShortcuts() 方法时，请记住，您可能只能在后台应用程序中调用这些方法特定的次数，这个应用程序当前没有任何 activities 或 services 。前景。可以调用这些方法的特定次数限制称为速率限制。此功能用于防止 ShortcutManager 过度消耗设备资源。

当速率限制激活时，isRateLimitingActive() 返回 true。但是，在某些事件中会重置速率限制，因此即使后台应用程序也可以调用 ShortcutManager 方法，直到再次达到速率限制。这些事件包括：

一个应用程序来到前台。
系统区域设置更改。
用户对通知执行 inline reply 操作。

如果在开发或测试期间遇到速率限制，可以从设备的设置中选择开发人员选项>重置ShortcutManager速率限制，或者您可以在 adb 中输入以下命令：

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

备份还原

通过在应用程序的清单文件中包含 android:allowBackup="true" 属性分配，您可以允许用户在更改设备时对应用程序执行备份和还原操作。如果您允许备份和还原，请记住以下有关应用程序快捷方式的要点：

静态快捷方式会自动重新发布，但只有用户在新设备上重新安装应用程序后才能重新发布。
不会备份动态快捷方式，因此您必须在应用中包含逻辑，以便在用户在新设备上打开您的应用时重新发布它们。
固定快捷方式会自动恢复到设备的启动器，但系统不会备份与固定快捷方式关联的图标。因此，您应该在应用中保存固定快捷方式的图像，以便在新设备上轻松恢复它们。

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

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val shortcutManager = getSystemService(ShortcutManager::class.java)

        if (shortcutManager!!.dynamicShortcuts.size == 0) {
            // 应用程序已还原。需要重新发布动态快捷方式。
            if (shortcutManager.pinnedShortcuts.size > 0) {
                // 已还原固定的快捷方式。
                // 使用 updateShortcuts() 确保它们包含最新信息。
            }

        }
    }
    // ...
}

其他资源

Android AppShortcuts 示例进一步演示了此页面上涵盖的工作流程的使用。