此页面由 Cloud Translation API 翻译。

创建快捷方式

快捷指令通过为用户提供帮助来传送特定类型的内容快速访问应用的各个部分

一张显示了应用快捷方式与固定快捷方式之间对比效果的图片 — **图 1.** 应用快捷方式和固定快捷方式。

通过快捷方式传送内容的方式取决于您的使用场景，以及快捷方式的上下文是由应用驱动或用户驱动的。虽然一个静态的快捷方式的上下文不会更改，而动态快捷方式的上下文会不断在这两种情况下，您的应用都会推动情境的增长。如果用户选择应用向其传送内容的方式，例如使用固定快捷方式，上下文由用户定义。以下场景介绍了几种用途每类快捷方式的情形：

静态快捷方式最适合使用一致的链接指向内容的应用在整个用户与产品互动的整个生命周期内 因为大多数启动器只显示四个静态快捷方式有助于执行日常安排以一致的方式执行任务，例如，在用户想要查看其日历或以特定方式发送电子邮件。
动态快捷方式用于在应用中执行的操作视具体情况而定。上下文相关快捷键是专为用户在应用中执行的操作例如，如果您开发了一款游戏用户在启动时从其当前关卡开始，您需要更新快捷方式。使用动态快捷方式可更新快捷方式每次用户通关时触发。
已固定快捷方式用于由用户执行的特定操作。例如：用户可能需要将特定网站固定到启动器。这是非常实用，因为它允许用户执行自定义操作，只需一步即可导航到该网站，这比使用默认浏览器实例。

创建静态快捷方式

静态快捷方式提供指向应用内常规操作的链接，这些操作必须在应用的当前版本生命周期内保持一致。对于静态快捷方式，不错的选项包括查看已发邮件、设置以及显示用户当天的锻炼活动。

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

在应用的 AndroidManifest.xml 文件中，找到符合以下条件的 activity：设置为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别。

将 <meta-data> 元素添加到此 activity，该元素引用应用的已定义快捷方式：

  <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>

注意：如果使用 activity-alias 在 activity 别名（而非其定位的 activity）中定义元数据使用 targetActivity 属性。

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

在新资源文件中，添加 <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.ComposeActivity" />
      <!-- 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 对象对其执行操作。

</ph> 注意：您不能将此属性的值设置为资源字符串，例如名称：@string/shortcut_id。

android:shortcutShortLabel

这是用于简短说明快捷方式用途的词组。如有可能，请将此简短说明限制在 10 个字符以内。

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

</ph> 注意：此属性的值必须是资源字符串，例如 @string/shortcut_short_label。

android:shortcutLongLabel

这是用于详细说明快捷方式用途的词组。如果有足够的则启动器会显示这个值，而不是 android:shortcutShortLabel。请尽可能限制限制为 25 个字符。

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

</ph> 注意：此属性的值必须是资源字符串，例如 @string/shortcut_long_label。

android:shortcutDisabledMessage

当用户尝试执行以下操作时，受支持的启动器中显示的消息：启动已停用的快捷方式消息必须向用户说明已停用。如果存在以下情况，此属性的值无效： android:enabled 为 true。

</ph> 注意：此属性的值必须是资源字符串，例如 @string/shortcut_disabled_message。

android:enabled

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

android:icon

位图或自适应启动器在向用户显示快捷方式时使用的图标。这个值可以是图片的路径，也可以是包含图片。尽可能使用自适应图标，以提升性能和一致性

配置内部元素

列出应用静态快捷方式的 XML 文件支持以下每个 <shortcut> 元素内的元素。您对于每个 API，必须包含一个 intent 内部元素您定义的静态快捷方式。

intent

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

</ph> 注意：此 intent 元素不能包含字符串资源。

您可以为一个快捷方式提供多个 intent。请参阅管理多个 intent 和 activity，设置一个 intent，而 TaskStackBuilder 类参考。

categories

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

有关支持的快捷方式类别的列表，请参阅 ShortcutInfo 类引用。

capability-binding

声明 capability 已与快捷方式关联

在前面的示例中，快捷方式与声明的 capability 相关联。用于 CREATE_MESSAGE、即与应用有关的 Action 。此功能绑定可让用户使用语音指令 Google 助理调用快捷方式。

创建动态快捷方式

动态快捷方式提供指向以下内容的链接：。这些操作可能会在使用应用期间和使用应用期间发生改变正在运行。动态快捷方式适合用于：呼叫特定人员、前往特定位置，并从用户上次的存档中加载游戏。您也可以使用动态快捷方式打开对话。

通过 ShortcutManagerCompat Jetpack 库是 ShortcutManager API：用于管理应用中的动态快捷方式。使用 ShortcutManagerCompat 库不仅减少了样板代码，还有助于确保快捷方式在所有 Android 版本中都能一致地运行。这个推送动态快捷方式时也需要一个库，这样在 Google 产品和服务（例如 Google 助理）上展示时， Google 快捷方式集成库。

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

推送和更新：使用 pushDynamicShortcut() 发布和更新动态快捷方式。如果已有动态或具有相同 ID 的固定快捷方式，每个可变的快捷方式都会更新。
移除：使用 removeDynamicShortcuts()。使用以下网址移除所有动态快捷方式： removeAllDynamicShortcuts()。

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

下例就是创建动态快捷方式并将其与您的 app：

Kotlin

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)

Java

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

ShortcutManagerCompat.pushDynamicShortcut(context, shortcut);

添加 Google 快捷方式集成库

Google 快捷方式集成库是一个可选的 Jetpack 库。它可让您推送可在 Android surface 上显示的动态快捷方式，例如以及 Google 界面（例如 Google 助理）。使用此库可帮助用户发现您的快捷方式，以便快速访问特定内容或重放操作。

例如，即时通讯应用可能会推送联系人的动态快捷方式名为“Alex”当用户发送消息后。动态快捷方式推送，如果用户对 Google 助理说“Hey Google，给小伟发消息” ExampleApp”，Google 助理可以启动 ExampleApp 并自动对其进行配置给 Alex 发消息。

随此库推送的动态快捷方式不受快捷键限制针对每台设备强制执行的。这样，您的应用可以在每次用户在您的应用中完成相关操作。将常用快捷方式推送至以便 Google 了解用户的使用模式，并根据上下文，提供相关的快捷方式

例如，Google 助理可以从 Google 助理推送的快捷指令中获取有用信息用户通常会在每天早上主动运行的健身跟踪应用建议你“开始跑步”当用户在 Google Play 上。

Google 快捷方式集成库未提供任何可寻址地址功能本身将此库添加到您的应用中后，Google surface 将能够。ShortcutManagerCompat

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

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

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

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

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

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

</ph> 注意：我们建议您使用 pushDynamicShortcut 推送动态快捷方式。您的应用可以使用其他方法发布快捷方式，但如果到达快捷键上限。

创建固定快捷方式

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

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

使用 isRequestPinShortcutSupported() 以验证设备的默认启动器是否支持应用内固定快捷方式。
使用以下两种方式之一创建 ShortcutInfo 对象：关于快捷方式是否存在：
1. 如果存在快捷方式，请创建一个 ShortcutInfo 对象，仅包含现有快捷方式的 ID。系统会找到并固定与快捷方式相关的其他信息。
2. 如果您要固定新的快捷方式，请创建一个ShortcutInfo 该对象包含 ID、intent 和新快捷方式。
。 <ph type="x-smartling-placeholder">
</ph> 注意：由于系统会执行备份并自动恢复已固定的快捷方式ID 必须包含稳定的常量字符串或服务器端标识符，本地生成的标识符可能对其他广告资源没有意义设备。
通过调用以下方法将快捷方式固定到设备的启动器上： requestPinShortcut()。在此过程中，您可以传入 PendingIntent 对象，该对象仅在快捷方式固定时通知您的应用成功。
<ph type="x-smartling-placeholder">
</ph> 注意：如果用户不允许将快捷方式固定到启动器，您的应用不会收到回调。

快捷方式固定后，您的应用可以使用 updateShortcuts() 方法。有关详情，请参阅更新快捷方式。

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

</ph> 注意：ShortcutManager 类的实例必须是使用 Context.getSystemService(Class) ，并将参数 ShortcutManager.class 或 Context.getSystemService(String) 参数为 Context.SHORTCUT_SERVICE。

Kotlin

val shortcutManager = getSystemService(ShortcutManager::class.java)

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)
}

Java

ShortcutManager shortcutManager =
        context.getSystemService(ShortcutManager.class);

if (shortcutManager.isRequestPinShortcutSupported()) {
    // Enable the existing shortcut with the ID "my-shortcut".
    ShortcutInfo pinShortcutInfo =
            new 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.
    Intent pinnedShortcutCallbackIntent =
            shortcutManager.createShortcutResultIntent(pinShortcutInfo);

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

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.getIntentSender());
}

</ph> 注意：另请参阅支持库 API isRequestPinShortcutSupported() 和 requestPinShortcut(), 适用于 Android 7.1（API 级别 25）及更低版本。支持库返回已弃用的 EXTRA_SHORTCUT_INTENT extra，以尝试固定流程。

创建自定义快捷方式 Activity

一张显示自定义对话框 activity 的图片，其中显示了提示“Do
您想将 Gmail 启动器图标添加到主屏幕吗？”自定义
可以选择“不用了”和“添加图标” — **图 2.** 自定义应用快捷方式对话框 activity 的示例。

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

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

系统启动应用的专用 Activity。
用户为快捷方式设置选项。
用户选择确认按钮。
您的应用使用 createShortcutResultIntent() 方法。此方法会返回 Intent, 然后应用将使用 setResult()。
您的应用调用 finish() 。

同样，您的应用可以提示用户将固定快捷方式添加到主屏幕或应用首次启动后显示在屏幕上此方法非常有效，因为它可以帮助您的用户创建快捷方式，普通工作流程

测试快捷键

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

触摸和按住应用的启动器图标，即可查看您定义的快捷方式。
拖动快捷方式，将其固定到设备的启动器。