快捷指令通过为用户提供帮助来传送特定类型的内容 快速访问应用的各个部分
![一张显示了应用快捷方式与固定快捷方式之间对比效果的图片](https://developer.android.google.cn/static/images/guide/topics/ui/shortcuts/pinned-shortcuts.png?authuser=0000&hl=ca)
通过快捷方式传送内容的方式取决于您的使用场景,以及 快捷方式的上下文是由应用驱动或用户驱动的。虽然一个静态的 快捷方式的上下文不会更改,而动态快捷方式的上下文会不断 在这两种情况下,您的应用都会推动情境的增长。如果用户 选择应用向其传送内容的方式,例如使用固定快捷方式, 上下文由用户定义。以下场景介绍了几种用途 每类快捷方式的情形:
- 静态 快捷方式 最适合使用一致的链接指向内容的应用 在整个用户与产品互动的整个生命周期内 因为大多数启动器 只显示四个 静态快捷方式有助于执行日常安排 以一致的方式执行任务,例如,在用户想要查看其日历或 以特定方式发送电子邮件 。
- 动态 快捷方式用于在应用中执行的操作 视具体情况而定。上下文相关快捷键是专为 用户在应用中执行的操作例如,如果您开发了一款游戏 用户在启动时从其当前关卡开始,您需要更新 快捷方式。使用动态快捷方式可更新快捷方式 每次用户通关时触发。
- 已固定 快捷方式用于由用户执行的特定操作。例如: 用户可能需要将特定网站固定到启动器。这是 非常实用,因为它允许用户执行自定义操作, 只需一步即可导航到该网站,这比使用默认 浏览器实例。
创建静态快捷方式
静态快捷方式提供指向应用内常规操作的链接,这些 操作必须在应用的当前版本生命周期内保持一致。 对于静态快捷方式,不错的选项包括查看已发邮件、设置 以及显示用户当天的锻炼活动。
如需创建静态快捷方式,请执行以下操作:
-
在应用的
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>
-
新建一个名为
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
-
一个字符串字面量,表示快捷方式在
<ph type="x-smartling-placeholder">ShortcutManager
对象对其执行操作。 -
android:shortcutShortLabel
-
这是用于简短说明快捷方式用途的词组。如有可能, 请将此简短说明限制在 10 个字符以内。
如需了解详情,请参阅
<ph type="x-smartling-placeholder">setShortLabel()
。 -
android:shortcutLongLabel
-
这是用于详细说明快捷方式用途的词组。如果有足够的 则启动器会显示这个值,而不是
android:shortcutShortLabel
。请尽可能限制 限制为 25 个字符。如需了解详情,请参阅
<ph type="x-smartling-placeholder">setLongLabel()
。 -
android:shortcutDisabledMessage
-
当用户尝试执行以下操作时,受支持的启动器中显示的消息: 启动已停用的快捷方式消息必须向用户说明 已停用。如果存在以下情况,此属性的值无效:
<ph type="x-smartling-placeholder">android:enabled
为true
。 -
android:enabled
-
确定用户是否可以与支持的快捷方式中的快捷方式进行交互 启动器。
android:enabled
的默认值为true
。如果将其设置为false
,请将android:shortcutDisabledMessage
,解释 停用快捷方式。如果您认为自己不需要提供此类消息, 将快捷方式从 XML 文件中完全移除。 -
android:icon
-
位图或 自适应 启动器在向用户显示快捷方式时使用的图标。这个 值可以是图片的路径,也可以是包含 图片。尽可能使用自适应图标,以提升性能和 一致性
<ph type="x-smartling-placeholder">
配置内部元素
列出应用静态快捷方式的 XML 文件支持以下
每个 <shortcut>
元素内的元素。您
对于每个 API,必须包含一个 intent
内部元素
您定义的静态快捷方式。
-
intent
-
用户选择快捷方式时系统启动的操作。 此 intent 必须为
<ph type="x-smartling-placeholder">android:action
提供一个值 属性。您可以为一个快捷方式提供多个 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 上显示。
创建固定快捷方式
在 Android 8.0(API 级别 26)及更高版本中,您可以创建固定快捷方式。 与静态和动态快捷方式不同,固定快捷方式显示在支持的 启动器图标。图 1 显示了这两者之间的区别 各种快捷方式
<ph type="x-smartling-placeholder">如需将快捷方式固定到使用您的应用的受支持启动器,请完成 操作步骤:
-
使用
isRequestPinShortcutSupported()
以验证设备的默认启动器是否支持应用内固定 快捷方式。 -
使用以下两种方式之一创建
ShortcutInfo
对象: 关于快捷方式是否存在:-
如果存在快捷方式,请创建一个
ShortcutInfo
对象, 仅包含现有快捷方式的 ID。系统会找到并固定 与快捷方式相关的其他信息。 -
如果您要固定新的快捷方式,请创建一个
ShortcutInfo
该对象包含 ID、intent 和新 快捷方式。
-
如果存在快捷方式,请创建一个
-
通过调用以下方法将快捷方式固定到设备的启动器上:
<ph type="x-smartling-placeholder">requestPinShortcut()
。 在此过程中,您可以传入PendingIntent
对象,该对象仅在快捷方式固定时通知您的应用 成功。快捷方式固定后,您的应用可以使用
updateShortcuts()
方法。有关详情,请参阅 更新 快捷方式。
以下代码段演示了如何创建固定快捷方式。
<ph type="x-smartling-placeholder">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()); }
创建自定义快捷方式 Activity
![一张显示自定义对话框 activity 的图片,其中显示了提示“Do
您想将 Gmail 启动器图标添加到主屏幕吗?”自定义
可以选择“不用了”和“添加图标”](https://developer.android.google.cn/static/images/guide/topics/ui/shortcuts/pinned-shortcuts-dialog.png?authuser=0000&hl=ca)
您还可以创建一个专门的 activity 来帮助用户创建快捷方式, 其中包含自定义选项和确认按钮图 2 显示了 Gmail 应用中此类活动的例子。
在应用的清单文件中,添加
ACTION_CREATE_SHORTCUT
添加到 activity 的
<intent-filter>
元素。此声明会设置以下行为:当用户尝试
创建快捷方式:
- 系统启动应用的专用 Activity。
- 用户为快捷方式设置选项。
- 用户选择确认按钮。
-
您的应用使用
createShortcutResultIntent()
方法。此方法会返回Intent
, 然后应用将使用setResult()
。 -
您的应用调用
finish()
。
同样,您的应用可以提示用户将固定快捷方式添加到主屏幕 或应用首次启动后显示在屏幕上此方法 非常有效,因为它可以帮助您的用户创建快捷方式, 普通工作流程
测试快捷键
如需测试应用的快捷方式,请在具有启动器的设备上安装您的应用 支持快捷键的功能。然后,执行以下操作:
- 触摸和按住应用的启动器图标,即可查看您定义的快捷方式 。
- 拖动快捷方式,将其固定到设备的启动器。