管理快捷方式

创建快捷方式后，您可能需要在 。例如，您可能想要确定 用户经常使用您的快捷方式完成特定操作。在另一个示例中 那么您不妨停用固定快捷方式 执行过时或缺失的操作。对于 您可能需要跟踪使用情况，以提供有改善效果的信号 快捷方式排名。

这一页介绍了这些方法以及其他几种管理 Google Analytics 的 快捷方式。

快捷方式的行为

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

快捷方式的可见性

静态快捷方式和动态快捷方式显示在支持的启动器或 在用户执行特定手势或语音指令时启动 Google 助理。已开启 支持的启动器，手势是触摸和按住应用的启动器图标， 但其他启动器应用中的手势可能有所不同。装有 Google 应用 Google 助理，快捷方式可以在 Google 助理中显示或由用户启动 语音指令。

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

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

  • 用户将其移除。
  • 与该快捷方式关联的应用被卸载。
  • 用户前往设置 >应用和通知、 选择该应用，然后点按存储 >清理存储空间。

共享目标 动态快捷方式的子集，显示在 Android Sharesheet。

Android Sharesheet 的屏幕截图
图 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 生成的项目将不再出现在 分享表单。

大多数启动器最多可显示四个快捷方式。对于 静态快捷方式和动态快捷方式时，启动器会显示 最多 2 个静态快捷方式和 2 个动态快捷方式。例如，如果您 定义四个静态快捷方式，并以编程方式创建三个动态快捷方式 快捷方式，启动器会显示前两个静态快捷方式，而两个 排名靠前的动态快捷方式。

管理多个 intent 和 Activity

如果您希望应用在用户激活 快捷方式，您可以将其配置为触发连续的活动。您可以 具体做法是，分配多个 intent，从 或者设置 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 快捷方式。如果不希望出现此行为，您可以使用 trampoline， activity — 启动另一个 activity 的不可见 activity， 调用 Activity.finish() 的 Activity.onCreate(Bundle)：

  1. 在 AndroidManifest.xml 文件中，添加属性分配 android:taskAffinity= 英寸。
  2. 在快捷方式资源文件中，引用 intent。

如需详细了解 trampoline 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，因为它最多只能显示 4 个 动态快捷方式。不过，c1、c2 和 c3 仍然是 用户可以访问并启动应用

然后，该用户总共可访问七个快捷方式，这些快捷方式链接到 。这是因为总数量包括 以及三个固定的快捷方式

  1. 应用可以使用 updateShortcuts(Context, List) 更新 现有的七个快捷键。例如，您可以更新这组快捷键 同级聊天的图标会随之更改
  2. 您可以使用 addDynamicShortcuts(Context, List) 和 setDynamicShortcuts(Context, List) 方法，用于更新现有快捷方式 并使用相同的 ID。但是，您不能使用它们来更新非动态、 固定快捷方式，因为这两种方法都会尝试转换给定列表， 动态快捷方式的快捷方式。

可以推送在其中显示的快捷方式数量没有限制 智能助理应用，例如 Google 助理。使用 pushDynamicShortcut() ShortcutManagerCompat Jetpack 库的方法来创建和更新 在助理应用程序上使用的快捷方式。另外，添加 Google 快捷方式集成 库，以使动态链接有资格显示在 Google 上 Google 助理。

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

处理系统语言区域的变更

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

跟踪快捷方式的使用情况

为了确定静态和动态快捷方式在哪些情况下出现， 启动器检查快捷方式的激活历史记录。对于静态快捷方式： 您可以跟踪用户何时在应用内完成特定操作 调用 reportShortcutUsed() 方法并向其传递 快捷方式：

  • 用户选择具有指定 ID 的快捷方式。
  • 在应用内，用户手动完成与应用中显示的 相同的快捷键。

您的应用通过调用 pushDynamicShortcut() 方法，并在调用 是否发生相关事件通过此方法推送动态快捷方式使用情况 智能助理应用（如 Google 助理）向用户建议相关快捷方式。 由于 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.
            }
        }
    }
    // ...
}