创建快捷方式

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

如何使用快捷方式传递内容取决于您的用例以及快捷方式的上下文是由应用驱动的还是由用户驱动的。虽然静态快捷方式的上下文不会改变而动态快捷方式的上下文会不断变化，但两种快捷方式的上下文都是由您的应用程序驱动的。如果用户选择他们希望您的应用向他们传递内容的方式，例如使用固定的快捷方式，则上下文由用户定义。以下列举了每种快捷方式类型的一些用例：

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

创建静态快捷方式

静态快捷方式提供了应用程序中通用操作的链接，这些操作应在应用程序当前版本的生命周期内保持一致。静态快捷方式的典型例子包括查看已发送的消息、设置警报以及显示当天用户的锻炼活动。

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

在应用程序的清单文件（AndroidManifest.xml）中，查找其Intent filter的操作（action）设置为android.intent.action.MAIN和类别（category）设置为android.intent.category.LAUNCHER的Activity。

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

创建一个新的资源文件：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" />
  </shortcut>
  <!-- Specify more shortcuts here. -->
</shortcuts>

自定义属性值

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

android:shortcutId

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

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

描述快捷方式意图（purpose）的简明短语（short description）。如果可能，将快捷方式的“short description”的长度限制为10个字符。有关更多信息，请参阅setShortLabel()

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

描述快捷方式意图（purpose）的扩展短语（long description）。如果有足够的空间，启动器会显示此值而不是android:shortcutShortLabel。如果可能，将快捷方式的“long description”的长度限制为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 或者adaptive icon。此值可以是图像的路径，也可以是包含图像的资源文件。应该尽可能使用自适应图标以提高性能和一致性。

注意：快捷方式图标不能包含tints.

配置内部元素

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

intent

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

注意：此intent元素不能包含字符串资源。您可以为单个快捷方式提供多个intent。有关详细信息，请参 Manage multiple intents and activities, Using intents和TaskStackBuilder类
categories

为应用程序快捷方式执行的操作类型提供分组，例如创建新的聊天消息。有关支持的快捷方式类别的列表，请参阅ShortcutInfo类。

创建动态快捷方式

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

ShortcutManager API允许你完成动态快捷键下面的操作：

**发布：**使用 setDynamicShortcuts()重新定义动态快捷方式的完整列表，或者使用addDynamicShortcuts() 以增加动态快捷方式的现有列表。
**更新：**使用updateShortcuts()方法。
删除：使用removeDynamicShortcuts()删除一组动态快捷方式或使用removeAllDynamicShortcuts()删除所有动态快捷方式。

有关在快捷方式上执行操作的更多信息，请阅读管理快捷方式和 ShortcutManager参考。

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

**注：**在ShortcutManager的实例中必须使用带有参数ShortcutManager.class的Context.getSystemService（Class）或带有Context.SHORTCUT_SERVICE参数的Context.getSystemService（String）获取ShortcutManager类的实例。

kotlin

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)

java

ShortcutManager shortcutManager = getSystemService(ShortcutManager.class);

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

shortcutManager.setDynamicShortcuts(Arrays.asList(shortcut));

创建固定快捷方式

图1：应用程序快捷方式和固定快捷方式的外观

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

**注意：**当您尝试将快捷方式固定到支持的启动器上时，用户会收到一个确认对话框，询问他们是否可以固定快捷方式。如果用户不允许固定快捷方式，则启动器会取消该请求。

要使用您的应用固定支持的启动器的快捷方式，请完成以下一系列步骤：

使用isRequestPinShortcutSupported()来验证设备的默认启动器是否支持应用程序固定快捷方式。
根据快捷方式是否已存在，以两种方式之一创建ShortcutInfo对象：
1. 如果快捷方式已存在，创建一个仅包含现有快捷方式ID的 ShortcutInfo对象。系统自动查找并固定与快捷方式相关的所有其他信息。
2. 如果要固定新的快捷方式，请创建一个包含新快捷方式ID、一个intent、一个short label的的ShortcutInfo对象
注意：由于系统会自动对固定快捷方式执行备份和还原(backup and restore)，因此这些快捷方式的ID应包含稳定的(stable)常量字符串或服务器端标识符，而不是本地生成的标识符，这些标识符在其他设备上可能没有意义。
尝试通过调用requestPinShortcut()将快捷方式固定到设备的启动器。在此过程中，您可以传入PendingIntent对象，该对象仅在快捷方式成功固定时通知您的应用。

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

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

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

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

kotlin

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

if (shortcutManager!!.isRequestPinShortcutSupported) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    val pinShortcutInfo = ShortcutInfo.Builder(context, "my-shortcut").build()

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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()) {
    // Assumes there's already a shortcut with the ID "my-shortcut".
    // The shortcut must be enabled.
    ShortcutInfo pinShortcutInfo =
            new ShortcutInfo.Builder(context, "my-shortcut").build();

    // Create the PendingIntent object only if your app needs to be notified
    // that the user allowed the shortcut to be pinned. Note that, if the
    // pinning operation fails, your app isn't notified. We assume here that the
    // app has implemented 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());
}

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

创建自定义快捷方式的Activity

图2:自定义应用程序快捷方式dialog Activity的示例

您还可以创建专门的Activity以帮助用户创建快捷方式，完成自定义选项（custom options）和确认按钮（confirmation button）。图2显示了Gmail应用中此类Activity的示例。

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

系统启动您应用的特定Activity。
用户设置快捷方式的选项。
用户选择确认按钮。
您的应用使用createShortcutResultIntent（）方法创建快捷方式。此方法返回一个Intent，您的应用程序使用setResult（）返回到先前执行的Activity。
您的应用程序调用finish（）以创建自定义快捷方式的Activity。

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

测试快捷方式

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

创建快捷方式

创建静态快捷方式

自定义属性值

配置内部元素

创建动态快捷方式

创建固定快捷方式

创建自定义快捷方式的Activity

测试快捷方式

FilesExpand file tree

创建快捷方式.md

Latest commit

History

创建快捷方式.md

File metadata and controls

创建快捷方式

创建静态快捷方式

自定义属性值

配置内部元素

创建动态快捷方式

创建固定快捷方式

创建自定义快捷方式的Activity

测试快捷方式