原文链接

快捷方式通过帮助用户快速访问 app 的某些部分，为用户提供特定类型的内容。

如何使用快捷方式提供内容取决于您的用例以及快捷方式的上下文是应用驱动还是用户驱动。 虽然静态快捷方式的上下文不会更改，并且动态快捷方式的上下文会不断更改，但两种情况下的上下文都是由您的应用程序驱动的。 如果用户选择他们希望您的应用向他们提供内容的方式，例如使用固定的快捷方式，则上下文由用户定义。 以下场景演示了每种快捷方式类型的一些用例：

• 静态快捷方式 最适合在用户与应用程序交互的整个生命周期内使用一致结构链接到内容的应用程序。 由于大多数启动器只能同时显示四个快捷方式，因此静态快捷方式对于常见  activities 非常有用。 例如，如果用户想要以特定方式查看他们的日历或电子邮件，则使用静态快捷方式可确保他们执行常规任务的体验是一致的。
• 动态快捷方式 用于对上下文敏感的应用程序中的操作。例如，如果您构建的游戏允许用户在启动时从当前级别开始，则需要频繁更新快捷方式。使用动态快捷方式可以在每次用户清除级别时更新快捷方式。
• 固定快捷方式用于特定的用户驱动操作。 例如，用户可能希望将特定网站固定到启动器。 这很有用，因为它允许用户执行自定义操作，例如一步导航到网站，比使用默认浏览器更快。

创建静态快捷方式

静态快捷方式提供到应用程序中常规操作的链接，这些操作在 app 当前版本的整个生命周期中都应保持一致。静态快捷方式的良好的候选者包括查看已发送的消息、设置警报和显示用户当天的锻炼活动。

要创建静态快捷方式，请完成以下步骤：

1. 在应用程序的清单文件（AndroidManifest.xml）中，查找其 intent 过滤器设置为 android.intent.action.MAIN action 和android.intent.category.LAUNCHER category 的 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> 元素都包含有关静态快捷方式的信息，包括其图标，描述标签以及它在应用程序中启动的 intents：

   <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" />
       <!-- 如果您的快捷方式与多个 intent 相关联，请在这里包含它们。 
            列表中的最后一个 intent 决定用户在启动这个快捷方式时看到的内容。 -->
       <categories android:name="android.shortcut.conversation" />
     </shortcut>
     <!-- 在此处指定更多快捷方式。-->
   </shortcuts>

    

自定义属性值

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

android:shortcutId

字符串文字，代表 ShortcutManager 对象对其执行操作的快捷方式。

注意：您不能将此属性的值设置为资源字符串，例如 @string/foo。

android:shortcutShortLabel

描述快捷方式目的的简明短语。 如果可能，将快捷方式的“简短描述”的长度限制为10个字符。

要获取更多信息，请参见 setShortLabel()。

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

android:shortcutLongLabel

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

要获取更多信息，参见 setLongLabel().

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

android:shortcutDisabledMessage

当用户尝试启动已禁用的快捷方式时，在支持的启动器中显示的消息。 该消息应向用户解释为什么现在禁用该快捷方式。 如果 android:enabled为 true，则此属性的值无效。

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

android:enabled

决定用户是否可以从支持的启动器与快捷方式进行交互。android:enabled 的默认值为 true。 如果将其设置为 false，则还应设置 android:shortcutDisabledMessage，以解释禁用快捷方式的原因。 如果您认为不需要提供此类消息，则最简单的方法是从 XML 文件中完全删除该快捷方式。

android:icon

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

注意：快捷方式图标不能包含色调。

配置内部元素

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

intent

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

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

您可以为单个快捷方式提供多个 intent。 有关详细信息，请参阅  Manage multiple intents and activities ，Using intents，和 TaskStackBuilder 类参考。

categories

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

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

创建动态快捷方式

动态快捷方式提供指向应用内特定的上下文相关操作的链接。 这些操作可能会在您的应用使用之间发生变化，甚至在您的应用运行时也会发生变化。动态快捷方式的良好候选者包括呼叫特定人员，导航到特定位置，以及从用户的最后保存点加载游戏。

ShortcutManager API 允许您在动态快捷方式上完成以下操作：

• 发布：使用 setDynamicShortcuts() 重新定义动态快捷方式的完整列表，或使用addDynamicShortcuts() 来扩充现有的动态快捷方式列表。
• 更新：使用 updateShortcuts() 方法。
• 删除：使用 removeDynamicShortcuts() 删除一组动态快捷方式，或使用 removeAllDynamicShortcuts().删除所有动态快捷方式。

For more information about performing operations on shortcuts, read Manage shortcuts and the ShortcutManagerreference.有关在快捷方式上执行操作的更多信息，请阅读 Manage shortcuts 和 ShortcutManager 参考。

以下代码段中显示了创建动态快捷方式并将其与您的 app 相关联的示例：

注意：必须使用带有参数 ShortcutManager.class 的 Context.getSystemService(Class) 或带有参数 Context.SHORTCUT_SERVICE 的 Context.getSystemService(String) 获取 ShortcutManager 类的实例。

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

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

shortcutManager!!.dynamicShortcuts = Arrays.asList(shortcut)

创建固定快捷方式

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

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

2. 根据快捷方式是否已存在，以两种方式之一创建 ShortcutInfo 对象：

   1. 如果快捷方式已存在，请创建仅包含现有快捷方式 ID 的 ShortcutInfo 对象。 系统自动查找并固定与快捷方式相关的所有其他信息。
   2. 如果要固定新快捷方式，请创建一个 ShortcutInfo 对象，其中包含新快捷方式的 ID，intent 和短标签。

   注意：由于系统会自动对固定快捷方式执行备份和还原，因此这些快捷方式的 ID 应包含稳定的常量字符串或服务器端标识符，而不是本地生成的标识符，这些标识符可能在其他设备上没有意义。

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

   注意：如果用户不允许将快捷方式固定到启动器，则您的应用程序不会收到回调。

   固定快捷方式后，您的应用可以使用 updateShortcuts() 方法更新其内容。 有关更多信息，请阅读更新快捷方式。

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

注意：必须使用带有参数 ShortcutManager.class 的 Context.getSystemService(Class) 或带有参数 Context.SHORTCUT_SERVICE 的 Context.getSystemService(String)获取 ShortcutManager 类的实例。

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

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // 假设已经有一个ID为 “my-shortcut” 的快捷方式。
    // 必须启用快捷方式。
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // 仅当需要通知您的应用程序用户允许固定快捷方式时，才创建 PendingIntent 对象。 
    // 请注意，如果固定操作失败，则不会通知您的应用。 我们假设应用程序已经实现了一个名为 
    //  createShortcutResultIntent() 的方法，该方法返回广播 itent。
    val pinnedShortcutCallbackIntent =         
shortcutManager.createShortcutResultIntent(pinShortcutInfo)

    // 配置 intent，以便应用程序的广播接收器成功获得回调。有关详细信息，请参阅            
    // PendingIntent.getBroadcast()。
    val successCallback = PendingIntent.getBroadcast(context, /* request code */ 0,
            pinnedShortcutCallbackIntent, /* flags */ 0)

    shortcutManager.requestPinShortcut(pinShortcutInfo,
            successCallback.intentSender)
}

注意：另请参阅 support 库 API，isRequestPinShortcutSupported() 和 requestPinShortcut()，它们适用于 Android 7.1（API 级别 25）及更低版本。support 库回退到已弃用的 EXTRA_SHORTCUT_INTENT extra 以尝试固定过程。

创建自定义快捷方式 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() 。

同样，您的应用可以提示用户在安装后或第一次启动应用时将固定快捷方式添加到主屏幕。 此方法很有效，因为它可以帮助您的用户在普通工作流程中创建快捷方式。

测试快捷方式

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

• 长按您应用的启动器图标，即可查看您为应用定义的快捷方式。
• 点击并拖动快捷方式将其固定到设备的启动器。