创建快捷方式

快捷方式可帮助用户快速访问您的应用的某些部分，从而为他们呈现特定类型的内容。

应用快捷方式与固定快捷方式的对比
图 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. 在新资源文件中，添加 <shortcuts> 根元素，其中包含 <shortcut> 元素的列表。在每个 <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对象对其执行操作时的快捷方式。

@string/shortcut_id
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

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

配置内部元素

列出应用静态快捷方式的 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 Surface（如 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 Surface（如启动器）和 Google Surface 上显示的动态快捷方式。您的用户可以轻松发现您的快捷方式，以便快速访问应用中的特定内容或重放操作。

通过此库推送的动态快捷方式不受对每台设备强制实施的 快捷方式限制的约束。这使得您的应用可以在用户每次在您的应用中完成关联操作时推送一个快捷方式。以这种方式推送常用快捷方式，Google 就可以了解您用户的使用方式，并根据情境向他们推荐相关的快捷方式。

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

Google 快捷方式集成库本身不提供任何可寻址功能。将此库添加到您的应用后，Google Surface 便可以使用 ShortcutManagerCompat 提取您的应用推送的快捷方式。

如需在应用中使用此库，请按以下步骤操作：

  1. 更新您的 gradle.properties 文件以支持 AndroidX 库：

    android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

  2. 在 app/build.gradle 中，添加 Google 快捷方式集成库和 ShortcutManagerCompat 的依赖项：

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

将库依赖项添加到 Android 项目后，您的应用就可以使用 ShortcutManagerCompat 中的 pushDynamicShortcut() 方法推送可以在启动器和相关 Google Surface 上显示的动态快捷方式。

创建固定快捷方式

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

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

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

  2. 使用以下两种方式之一创建 ShortcutInfo 对象，具体采用哪种方式取决于快捷方式是否存在：

    1. 如果快捷方式存在，请创建仅包含现有快捷方式 ID 的 ShortcutInfo 对象。系统会自动找到与该快捷方式相关的所有其他信息，并将其固定。
    2. 如果您要固定原本不存在的新快捷方式，请创建包含新快捷方式 ID、intent 和简短标签的 ShortcutInfo 对象。

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

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

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

val shortcutManager = getSystemService<ShortcutManager>()

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Enable the existing shortcut with the ID "my-shortcut".
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").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 = shortcutManager.createShortcutResultIntent(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 */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

创建自定义快捷方式 activity

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

您还可以创建一个专用 activity 来帮助用户创建快捷方式，同时提供自定义选项和确认按钮。图 2 显示了 Gmail 应用中此类 activity 的一个示例。

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

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

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

测试快捷方式

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

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