创建快捷方式

快捷方式可帮助用户快速访问应用的各个部分，从而向用户提供特定类型的内容。

应用快捷方式与固定快捷方式之间的对比
图 1. 应用快捷方式和固定的快捷方式。

您如何通过快捷方式提供内容取决于您的使用情形，以及快捷方式的上下文是应用驱动的还是用户驱动的。虽然静态快捷方式的上下文不会发生变化，而动态快捷方式的上下文会不断变化，但在这两种情况下，上下文都由您的应用驱动。如果用户选择应用向其提供内容的方式（例如通过固定的快捷方式），则上下文由用户定义。以下场景描述了每种快捷方式类型的一些使用情形：

  • 静态快捷方式最适合在用户与应用互动期间始终使用一致结构链接到内容的应用。由于大多数启动器一次只显示四个快捷方式，因此静态快捷方式非常适合以一致的方式执行常规任务，例如用户想要以特定方式查看日历或电子邮件。
  • 动态快捷方式用于应用中与上下文相关的操作。情境相关快捷方式是根据用户在应用中执行的操作量身定制的。例如，如果您构建的游戏允许用户从启动时的当前级别开始，则需要经常更新快捷方式。使用动态快捷方式可让您在用户每次通关时更新快捷方式。
  • 固定快捷方式用于特定的用户驱动操作。例如，用户可能希望将特定网站固定到启动器。这很有用，因为它可以让用户执行自定义操作，例如一步到位地前往网站，比使用浏览器的默认实例更快。

创建静态快捷方式

静态快捷方式提供指向应用内通用操作的链接，这些操作在应用当前版本的整个生命周期内必须保持一致。静态快捷方式的理想选项包括查看已发送的消息、设置闹钟以及显示用户当天的锻炼活动。

如需创建静态快捷方式，请执行以下操作：

  1. 在应用的 AndroidManifest.xml 文件中，找到 intent 过滤器设为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 activity。

  2. 向此 activity 添加一个 <meta-data> 元素，用于引用定义应用快捷方式的资源文件：

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.myapplication">
  <application ... >
    <activity android:name="Main">
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
      <meta-data android:name="android.app.shortcuts"
                 android:resource="@xml/shortcuts" />
    </activity>
  </application>
</manifest>

  3. 创建一个名为 res/xml/shortcuts.xml 的新资源文件。

  4. 在新资源文件中，添加一个包含 <shortcut> 元素列表的 <shortcuts> 根元素。在每个 <shortcut> 元素中，都包含有关静态快捷方式的信息，包括其图标、说明标签以及在应用内启动的 intent：

    <shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/compose_icon"
    android:shortcutShortLabel="@string/compose_shortcut_short_label1"
    android:shortcutLongLabel="@string/compose_shortcut_long_label1"
    android:shortcutDisabledMessage="@string/compose_disabled_message1">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapplication"
      android:targetClass="com.example.myapplication.Main" />
    <!-- If your shortcut is associated with multiple intents, include them
         here. The last intent in the list determines what the user sees when
         they launch this shortcut. -->
    <categories android:name="android.shortcut.conversation" />
    <capability-binding android:key="actions.intent.CREATE_MESSAGE" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>

自定义属性值

以下列表包含对静态快捷方式中不同属性的说明。为 android:shortcutId 和 android:shortcutShortLabel 提供值。所有其他值都是可选的。

android:shortcutId

一个字符串字面量，表示 ShortcutManager 对象对其执行操作时的快捷方式。

android:shortcutShortLabel

用于描述快捷方式用途的简明短语。如果可能，请将此简短说明限制在 10 个字符以内。

如需了解详情，请参阅 setShortLabel()。

android:shortcutLongLabel

用于描述快捷方式用途的扩展短语。如果有足够的空间，启动器会显示此值，而不是 android:shortcutShortLabel。如果可能，请将此长说明限制为 25 个字符。

如需了解详情，请参阅 setLongLabel()。

android:shortcutDisabledMessage

当用户尝试启动已停用的快捷方式时，在受支持的启动器中显示的消息。消息必须向用户说明快捷方式被停用的原因。如果 android:enabled 为 true，此属性的值不会产生任何影响。

android:enabled

确定用户是否可以从受支持的启动器与快捷方式进行互动。android:enabled 的默认值为 true。 如果您将其设置为 false，请设置 android:shortcutDisabledMessage 来解释停用快捷方式的原因。如果您认为无需提供此类消息，请从 XML 文件中完全移除该快捷方式。

android:icon

启动器在向用户显示快捷方式时使用的 bitmap 或自适应图标。此值可以是图片或包含图片的资源文件的路径。尽可能使用自适应图标，以提高性能和一致性。

配置内部元素

列出应用的静态快捷方式的 XML 文件支持每个 <shortcut> 元素内的以下元素。您必须为定义的每个静态快捷方式添加一个 intent 内部元素。

intent

用户选择快捷方式时系统启动的操作。此 intent 必须为 android:action 属性提供值。

您可以为一个快捷方式提供多个 intent。如需了解详情，请参阅管理多个 intent 和 activity、设置 intent 和 TaskStackBuilder 类参考。

categories

提供应用快捷方式执行的操作类型的分组，例如创建新的聊天消息。

如需查看支持的快捷方式类别列表，请参阅 ShortcutInfo 类参考文档。

capability-binding

声明与快捷方式关联的功能。

在前面的示例中，快捷方式与为 CREATE_MESSAGE 声明的功能相关联，而 CREATE_MESSAGE 是 与应用有关的 Action 内置 intent。此功能绑定可让用户通过 Google 助理使用语音指令来调用快捷方式。

创建动态快捷方式

动态快捷方式提供指向应用内特定的上下文相关操作的链接。这些操作可能会在应用的不同使用场景间发生变化，甚至会在应用运行时发生变化。动态快捷方式的适用场景包括致电特定人员、导航到特定位置，以及从用户的上一个存档点加载游戏。您也可以使用动态快捷方式打开对话。

ShortcutManagerCompat Jetpack 库是 ShortcutManager API 的帮助程序，可让您管理应用中的动态快捷方式。使用 ShortcutManagerCompat 库可减少样板代码，并有助于确保各个 Android 版本的快捷方式保持一致。此外，如需推送动态快捷方式，以便它们能够通过 Google 快捷方式集成库在 Google 产品界面（例如 Google 助理）上显示，也需要使用此库。

借助 ShortcutManagerCompat API，您的应用可以通过动态快捷方式执行以下操作：

如需详细了解如何对快捷方式执行操作，请参阅管理快捷方式和 ShortcutManagerCompat 参考文档。

以下示例展示了如何创建动态快捷方式并将其与应用相关联：

val shortcut = ShortcutInfoCompat.Builder(context, "id1")
    .setShortLabel("Website")
    .setLongLabel("Open the website")
    .setIcon(IconCompat.createWithResource(context, R.drawable.icon_website))
    .setIntent(
        Intent(
            Intent.ACTION_VIEW,
            Uri.parse("https://www.mysite.example.com/")
        )
    )
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut)

添加 Google 快捷方式集成库

Google 快捷方式集成库是一个可选的 Jetpack 库。借助此库，您可以推送可在 Android 界面（例如启动器）和 Google 界面上显示的动态快捷方式。使用此库有助于用户发现您的快捷方式，以便快速访问特定内容或在您的应用中再次执行操作。

使用此库推送的动态快捷方式不受按设备强制执行的快捷方式限制约束。这样一来，您的应用便可在用户每次完成关联操作时推送快捷方式。通过这种方式推送常用快捷方式，可让 Google 了解用户的使用模式，并向用户建议上下文相关的快捷方式。

例如，Google 助理可以从健身追踪应用推送的快捷方式中了解到，用户通常每天早上跑步，因此当用户早上拿起手机时，Google 助理会主动建议“开始跑步”快捷方式。

Google Shortcuts Integration 库本身不提供任何可寻址的功能。将此库添加到应用后，Google 产品界面便可接收应用使用 ShortcutManagerCompat 推送的快捷方式。

如需在应用中使用此库，请将 Google 快捷方式集成库和 ShortcutManagerCompat 的依赖项添加到 app/build.gradle 或 app/build.gradle.kts 文件中：

Kotlin

dependencies {
    implementation("androidx.core:core:1.6.0")
    implementation("androidx.core:core-google-shortcuts:1.0.0")
}

Groovy

dependencies {
    implementation "androidx.core:core:1.6.0"
    implementation 'androidx.core:core-google-shortcuts:1.0.0'
}

将库依赖项添加到 Android 项目后，您的应用可以使用 ShortcutManagerCompat 中的 pushDynamicShortcut() 方法来推送符合条件的动态快捷方式，以便在启动器和参与的 Google 平台上显示。

创建固定快捷方式

在 Android 8.0（API 级别 26）及更高版本中，您可以创建固定快捷方式。与静态和动态快捷方式不同，已固定的快捷方式在受支持的启动器中显示为单独的图标。图 1 显示了这两种类型的快捷方式之间的区别。

如需使用您的应用将快捷方式固定到受支持的启动器，请完成以下步骤：

  1. 使用 isRequestPinShortcutSupported() 验证设备的默认启动器是否支持应用内固定快捷方式。

  2. 创建一个 ShortcutInfoCompat 对象，其中包含快捷方式的 ID、intent 和简短标签。如果快捷指令存在，请使用现有快捷指令的 ID。系统会自动查找并固定与快捷方式相关的所有其他信息。

  3. 通过调用 requestPinShortcut() 将快捷方式固定到设备的启动器。在此过程中，您可以传入一个 PendingIntent 对象，该对象仅在快捷方式成功固定时通知您的应用。

    快捷方式固定后，应用可以使用 updateShortcuts() 方法更新其内容。如需了解详情，请参阅更新快捷方式。

以下代码段演示了如何创建固定快捷方式：

if (ShortcutManagerCompat.isRequestPinShortcutSupported(context)) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfoCompat.Builder(context, "my-shortcut")
        .setShortLabel("Website")
        .setIntent(
            Intent(
                Intent.ACTION_VIEW,
                Uri.parse("https://www.mysite.example.com/")
            )
        )
        .build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user let the shortcut be pinned. If the pinning operation fails,
    // your app isn't notified. Assume here that the app implements a method
    // called createShortcutResultIntent() that returns a broadcast intent.
    val pinnedShortcutCallbackIntent =
        ShortcutManagerCompat.createShortcutResultIntent(context, pinShortcutInfo)

    // Configure the intent so that your app's broadcast receiver gets the
    // callback successfully. For details, see PendingIntent.getBroadcast().
    val successCallback = PendingIntent.getBroadcast(
        context, /* request code */ 0,
        pinnedShortcutCallbackIntent, /* flags */ PendingIntent.FLAG_IMMUTABLE
    )

    ShortcutManagerCompat.requestPinShortcut(
        context,
        pinShortcutInfo,
        successCallback.intentSender
    )
}

创建自定义快捷方式 Activity

显示提示“您要将 Gmail 启动器图标添加到主屏幕吗？”的自定义对话框 activity。自定义选项包括“不用了”和“添加图标”。
图 2. 自定义应用快捷方式对话框 activity 的示例。

您还可以创建一个专门的 activity，帮助用户创建快捷方式，其中包含自定义选项和确认按钮。图 2 显示了 Gmail 应用中此类活动的示例。

在应用的清单文件中，将 ACTION_CREATE_SHORTCUT 添加到 activity 的 <intent-filter> 元素中。此声明在用户尝试创建快捷方式时设置了以下行为：

  1. 系统会启动应用的专用 activity。
  2. 用户为快捷指令设置选项。
  3. 用户选择确认按钮。
  4. 应用使用 createShortcutResultIntent() 方法创建快捷方式。此方法会返回一个 Intent，您的应用会使用 setResult() 将其传递回之前执行的 activity。
  5. 您的应用在用于创建自定义快捷方式的 activity 上调用 finish()。

同样，您的应用可以在安装后或首次启动时提示用户将固定的快捷方式添加到主屏幕。此方法之所以有效，是因为它有助于用户在日常工作流程中创建快捷方式。

测试快捷方式

如需测试应用的快捷方式，请将应用安装在支持快捷方式的启动器所在的设备上。然后，执行以下操作：

  • 轻触并按住应用的启动器图标，即可查看您为应用定义的快捷方式。
  • 拖动快捷方式以将其固定到设备的启动器。
上一页
快捷方式简介
下一页
为快捷方式添加功能