管理快捷方式

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

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

快捷方式行为

以下各节包含有关快捷方式行为的常规信息，包括可见性、显示顺序和排名。

快捷方式可见性

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

class="devsite-code" translate="no" dir="ltr">LauncherApps 类提供了供启动器应用访问快捷方式的 API。

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

• 用户将其移除。
• 与该快捷方式关联的应用已卸载。
• 用户可以通过依次进入设置 > 应用和通知，选择应用，然后依次点按存储 > 清除存储来清除应用的数据。

分享目标是动态快捷方式的一个子集，它们出现在 Android 分享表单的直接分享行中。

快捷方式显示顺序

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

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

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

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

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

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

管理多个 intent 和 activity

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

分配多个 intent

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

从一个 activity 启动另一个 activity

静态快捷方式不能有自定义 intent 标志。静态快捷方式的第一个 intent 始终设置了 Intent.FLAG_ACTIVITY_NEW_TASK 和 Intent.FLAG_ACTIVITY_CLEAR_TASK。这意味着当您的应用运行时，启动静态快捷方式时，应用中所有现有的 activity 都会被销毁。如果您不想要这种行为，您可以在 Activity.onCreate(Bundle) 中使用一个跳转 Activity（一个不可见的 activity，用于启动另一个 activity），它会调用 Activity.finish()

1. 在 AndroidManifest.xml 文件中，在跳转 Activity 中包含属性赋值 android:taskAffinity=""。
2. 在快捷方式资源文件中，在静态快捷方式内的 intent 中引用跳转 Activity。

有关跳转 Activity 的更多信息，请参阅从一个 activity 启动另一个 activity。

设置 intent 标志

您可以使用任意一组 Intent 标志来发布动态快捷方式。最好同时指定 Intent.FLAG_ACTIVITY_CLEAR_TASK 和其他标志。否则，如果您的应用正在运行时尝试启动另一个任务，目标 activity 可能不会显示。

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

更新快捷方式

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

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

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

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

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

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

1. 应用可以使用 updateShortcuts(Context, List) 更新任何现有的七个快捷方式。例如，当聊天对手的图标更改时，您可能会更新这组快捷方式。
2. 您可以使用 addDynamicShortcuts(Context, List) 和 setDynamicShortcuts(Context, List) 方法更新具有相同 ID 的现有快捷方式。但是，您不能使用它们来更新非动态的固定快捷方式，因为这两个方法会尝试将给定的快捷方式列表转换为动态快捷方式。

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

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

处理系统语言区域更改

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

跟踪快捷方式使用情况

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

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

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

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

禁用快捷方式

由于您的应用及其用户可以将快捷方式固定到设备的启动器上，因此这些固定的快捷方式可能会将用户定向到应用中已过时或不再存在的操作。为了管理这种情况，您可以通过调用 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 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.
            }

        }
    }
    // ...
}

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 updateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}