管理快捷方式

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

此页面描述了这些以及其他几种常见的管理快捷方式的方法。

快捷方式行为

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

快捷方式可见性

当用户执行特定手势或语音命令时，静态快捷方式和动态快捷方式会出现在受支持的启动器或助手程序中。在受支持的启动器上，手势是触摸并按住应用的启动器图标，但在其他启动器应用上，手势可能有所不同。对于 Google 助手，快捷方式可以在助手程序中显示或从用户语音命令启动。

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

由于固定快捷方式出现在启动器本身中，因此它们始终可见。只有在以下情况下，才会从启动器中删除固定快捷方式

用户将其删除。
与快捷方式关联的应用已卸载。
用户通过转到设置 > 应用和通知，选择该应用，然后点击存储 > 清除存储空间来清除应用的数据。

共享目标是出现在 Android 共享表单的直接共享行中的动态快捷方式的子集。

A screenshot of Android Sharesheet — **图 1.** Android 共享表单。直接共享目标出现在第一行，然后是排名应用，最后是应用列表。

快捷方式显示顺序

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

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

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

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

共享目标的顺序基于各种因素，包括过去的用户历史记录、最近使用情况、频率、排名提示、应用使用情况以及与共享快捷方式关联的对话中设置的优先级。使用共享快捷方式 API创建的共享目标优先于Android 11中已弃用的ChooserTargetService生成的共享目标。在Android 12及更高版本中，已弃用的ChooserTargetService生成的共享目标将不再出现在共享表单中。

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

管理多个意图和活动

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

分配多个意图

使用ShortcutInfoCompat.Builder创建快捷方式时，您可以使用setIntents()而不是setIntent()。通过调用setIntents()，当用户选择快捷方式时，您可以启动应用中的多个活动，并将列表中除最后一个活动以外的所有活动都放在返回堆栈中。如果用户然后点击设备的返回按钮，他们会看到应用中的另一个活动，而不是返回到设备的启动器。

从另一个活动启动一个活动

静态快捷方式不能有自定义意图标志。静态快捷方式的第一个意图始终具有Intent.FLAG_ACTIVITY_NEW_TASK和Intent.FLAG_ACTIVITY_CLEAR_TASK set。这意味着当您的应用正在运行时，启动静态快捷方式时，应用中的所有现有活动都会被销毁。如果您不希望出现此行为，您可以使用跳板活动——一个不可见的活动，它会在Activity.onCreate(Bundle) 中调用Activity.finish()来启动另一个活动。

在AndroidManifest.xml文件中，在跳板活动中包含属性赋值android:taskAffinity=""。
在快捷方式资源文件中，在静态快捷方式内的意图中引用跳板活动。

有关跳板活动的更多信息，请参阅从另一个活动启动一个活动。

设置意图标志

您可以发布具有任何一组Intent标志的动态快捷方式。最好与其他标志一起指定Intent.FLAG_ACTIVITY_CLEAR_TASK。否则，如果您尝试在应用运行时启动另一个任务，则目标活动可能不会出现。

要了解有关任务和意图标志的更多信息，请参阅任务和返回堆栈。

更新快捷方式

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

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

考虑以下示例，该示例假设getMaxShortcutCountPerActivity()返回的值为4。

一个聊天应用发布四个动态快捷方式，代表四个最近的对话：c1、c2、c3和c4。
用户将所有四个快捷方式都固定。
稍后，用户又开始了三个对话：c5、c6和c7。发布者应用重新发布其动态快捷方式。新的动态快捷方式列表是：c4、c5、c6和c7。

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

然后，用户可以访问总共七个链接到发布者应用中活动的快捷方式。这是因为总数包括最大快捷方式数量和三个固定快捷方式。

应用可以使用updateShortcuts(Context, List)更新任何现有的七个快捷方式。例如，当聊天伙伴的图标发生变化时，可以更新这组快捷方式。
可以使用addDynamicShortcuts(Context, List)和setDynamicShortcuts(Context, List)方法使用相同的ID更新现有的快捷方式。但是，不能使用它们来更新非动态的固定快捷方式，因为这两种方法都试图将给定的快捷方式列表转换为动态快捷方式。

对于Google Assistant等助手应用显示的快捷方式数量没有限制。使用pushDynamicShortcut()（ShortcutManagerCompat Jetpack库的方法）来创建和更新可在助手应用中使用的快捷方式。此外，将Google快捷方式集成库添加到您的应用中，以使动态链接有资格出现在Google Assistant上。

要了解有关应用快捷方式指南的更多信息，包括更新快捷方式，请参阅快捷方式最佳实践。

处理系统区域设置更改

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

跟踪快捷方式使用情况

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

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

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

对于与对话相关的快捷方式，跟踪发送和接收消息的使用情况非常重要。详情请参阅人员和对话最佳实践。

禁用快捷方式

由于您的应用及其用户可以将快捷方式固定到设备的启动器，因此这些固定的快捷方式可能会引导用户执行应用中已过期或不再存在的操作。为了管理这种情况，您可以通过调用disableShortcuts禁用不想让用户选择的快捷方式，这会将指定的快捷方式从静态和动态快捷方式列表中移除，并禁用这些快捷方式的固定副本。您还可以使用此方法的重载版本，该版本接受CharSequence作为自定义错误消息。然后，当用户尝试启动任何禁用的快捷方式时，该错误消息就会出现。

速率限制

使用setDynamicShortcuts()、addDynamicShortcuts()或updateShortcuts()方法时，可能只能在后台应用（即没有活动或服务处于前台的应用）中调用这些方法特定次数。调用这些方法的特定次数的限制称为速率限制。此功能可防止ShortcutManagerCompat过度消耗设备资源。

当速率限制处于活动状态时，isRateLimitingActive()将返回true。但是，速率限制会在某些事件期间重置，因此即使是后台应用也可以调用ShortcutManager方法，直到再次达到速率限制为止。这些事件包括：

应用进入前台。
系统区域设置发生更改。
用户对通知执行内联回复操作。

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

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

备份和还原

通过在应用的清单文件中包含android:allowBackup="true"属性赋值，可以让用户在更改设备时对应用执行备份和还原操作。如果支持备份和还原，请记住以下关于应用快捷方式的要点：

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

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

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

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

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}