创建 shortcuts.xml

确定应用内功能和要实施的相应内置意图 (BII) 后，请通过在 shortcuts.xml 资源文件中定义 capability 元素来声明您的功能支持的 BII。将 BII 声明为 capability 会在您的应用中注册对该语义意图的支持，并允许使用 Google 助理通过语音查询来实现该意图。

助理使用自然语言处理从用户查询中提取参数。内置意图参考列出了每个 BII 能够从关联的用户查询中提取的字段。例如，如果用户通过说“嘿 Google，在 ExampleApp 中从 ExampleCafe 点一份披萨”来调用应用中的 actions.intent.ORDER_MENU_ITEM 功能，则助理会从用户请求中提取以下 BII 参数

menuItem.name = “披萨”
menuItem.inMenuSection.inMenu.forRestaurant.name = “ExampleCafe”

助理会将 BII 参数传递到 capability 中定义的实现 intent。可以在功能中定义一个或多个 intent 元素，以适应用户调用 BII 的不同方式。例如，您可以定义一个实现 intent，该意图需要上述示例中的两个 BII 参数。然后，您可以定义第二个意图，该意图只需要一个 BII 参数 menuItem.name，如果用户发出更简单的请求（例如“嘿 Google，在 ExampleApp 上点一份披萨”），则该意图会显示附近的餐厅选项。

概述

您可以使用放置在应用项目 res/xml 目录中的 shortcuts.xml 文件配置应用操作，然后在应用清单中创建对 shortcuts.xml 的引用。请按照以下步骤在应用清单中添加对 shortcuts.xml 的引用

在应用的清单文件（AndroidManifest.xml）中，找到其意图过滤器设置为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的活动。
使用 <meta-data> 标记在具有 MAIN 和 LAUNCHER 两个意图过滤器的 Activity 中，在 AndroidManifest.xml 中添加对 shortcuts.xml 的引用，如下所示
```
<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />
```

以上示例声明了 APK 中 xml/shortcuts.xml 文件的 XML 资源。如需详细了解如何配置快捷方式，请参阅 Android 开发者文档中的创建静态快捷方式。

Android 项目中需要使用 Jetpack 库 androidx.core:core:1.6.0（或更高版本）才能避免在 shortcuts.xml 中定义应用操作功能时出现编译错误。如需了解详情，请参阅 Android Jetpack 入门。

静态快捷方式

在定义 capability 时，您可以在 shortcuts.xml 中声明静态 shortcut 元素以扩展功能。在您将版本上传到 Google Play Console 时，助理会提取静态快捷方式。由于静态快捷方式只能通过创建新版本来创建和更新，因此它们最适合突出显示应用中的常见活动和内容。

您可以使用静态快捷方式启用以下应用操作功能

功能快捷方式。创建启动包含预定义意图参数值的功能实例的快捷方式。例如，您可以声明一个应用快捷方式“开始跑步”，它会在您的健身应用中调用START_EXERCISE内置意图功能。

这些快捷方式包含意图、shortLabel和longLabel属性，使它们有资格在主动界面（如 Google 助理或在 Android 启动器上长按应用图标时）中被建议并作为芯片来完成。操作快捷方式还可以通过使用<capability-binding>标签将其与功能关联，充当下面详细介绍的实体快捷方式。
实体快捷方式。实体快捷方式为功能的语音查询完成提供受支持的参数值列表。例如，一个实体快捷方式，其中包含与START_EXERCISE功能的exercise.name内置意图参数绑定的练习类型列表（“远足”、“跑步”等）。如果用户话语与某个实体匹配，则shortcutId ID 将传递给意图，而不是原始用户查询值。

实体快捷方式不定义意图、shortLabel或longLabel属性，因此不会在主动界面上建议。有关详细信息，请参阅应用操作的内联清单。

注意：声明为实体快捷方式的静态快捷方式会被LauncherApps API删除，这意味着它们对 Android 启动器可用。

功能架构

下表描述了shortcuts.xml中功能元素的应用操作架构。包含标签时，除非标记为“可选”，否则其所有属性都是必需的。

Shortcuts.xml 标签	包含于	属性
`<capability>`	`<shortcuts>`	`android:name` `app:queryPatterns`（仅适用于自定义意图）
`<intent>`	`<capability>`	`android:action`（可选） `android:targetClass`（可选） `android:targetPackage`（可选） `android:data`（可选）
`<url-template>`	`<intent>`	`android:value`
`<extra>`	`<intent>`	`android:key` `android:value` 仅适用于前台应用调用
`<parameter>`	`<intent>`	`android:name` `android:key` `android:mimeType`（仅适用于自定义意图） `android:required`（可选） `app:shortcutMatchRequired`（可选）
`<data>`	`<parameter>`	`android:pathPattern`（仅适用于 Web 清单）
`<shortcut-fulfillment>`	`<capability>`	仅适用于内联清单
`<parameter>`	`<shortcut-fulfillment>`	`android:name`
`<slice>`	`<capability>`	仅适用于Android 切片

功能架构描述

本节描述功能架构元素。

<capability>

定义应用操作意图的功能，您的应用支持该意图。您shortcuts.xml文件中每个<capability>元素都必须提供至少一个<intent>来处理操作的完成。

属性

android:name：内置意图操作 ID（例如，actions.intent.CREATE_TAXI_RESERVATION）。有关受支持的内置意图列表，请参阅内置意图参考。
app:queryPatterns：此意图预期来自用户的查询的字符串数组资源。此属性仅适用于自定义意图，因为内置意图已包含用户表达其尝试执行的任务或他们寻求的信息的常用方式的模型。

<intent>

定义如何使用应用内功能完成用户查询的 Android意图元素。开发人员可以在功能中提供多个<intent>标签。Google 助理尝试使用功能中第一个所有必需参数都提供的<intent>来完成用户查询。

属性

android:action：意图操作类型。默认为ACTION_VIEW。
android:targetClass：目标 Activity 类，例如："com.example.food.OrderActivity"
android:targetPackage：包含目标 Activity 类的包，例如："com.example.food"
android:data：如果在意图中声明了<url-template>标签，则此字段会被覆盖。

<url-template>

用于构造要在设备上打开的深层链接 URI 的模板。如果模板的所有必需参数都可用，则可以使用内置意图参数扩展模板。有关 HTTP URL 模板的示例，请参阅维基百科关于 URL 模板的文章。模板格式遵循RFC6570 URI 模板规范。

以下是一些 URL 模板值的示例

模板	值	扩展值
`https://example.com/test{?foo,bar}`	`"foo": "123"` `"bar": "456"`	`https://example.com/test?foo=123&bar=456`
`https://example.com/test?utm_campaign=appactions{&foo,bar}`	`"foo": "123"` `"bar": "456"`	`https://example.com/test?utm_campaign=appactions&foo=123&bar=456`
`https://example.com/test?utm_campaign=appactions{#foo}`	`"foo": "123"`	`https://example.com/test?utm_campaign=appactions#foo=123`
`myapp://example/{foo}`	`"foo": "123"`	`myapp://example/123`

有关配置 URL 模板的更多信息，请参阅完成中的 URL 模板。

<extra>

定义意图的额外数据。对于应用操作，此字段仅用于为功能启用前台应用调用。

<parameter>

将内置意图参数映射到意图参数值。有关更多信息，请参阅参数数据和匹配。

属性

android:name：要与此意图参数关联的内置意图参数的名称。该名称应为内置意图参数的叶子级字段（例如，foodObservation.aboutFood.name）。
android:key：内置意图参数值的开发人员定义的键。例如，您可以为message.recipient.name内置意图参数定义contact_name。
android:mimeType：参数的 mimeType，例如text/*。此字段仅对于自定义意图的参数是必需的。
android:required：声明用户查询是否需要包含此参数才能使用此意图进行完成。如果参数不可用，则 Google 助理尝试使用为功能定义的下一个意图来完成用户查询。

<data>

将Web 清单与参数关联。

属性

android:pathPattern：使用 Web 清单返回的实体 URL 的 URL 模式。此属性支持两个通配符
- *：星号匹配紧邻其前面的字符的零个或多个出现。
- .*：句点后跟星号匹配任何零个或多个字符的序列。
- 转义字符仅在需要文字*和\时才需要，您可以分别将其转义为\\*和\\\\。

<shortcut-fulfillment>

指定为指定参数的内联清单快捷方式中定义的意图用于完成。有关详细信息，请参阅使用快捷方式意图完成。

<parameter>（对于`<shortcut-fulfillment>`）

可选属性，用于将单个内置意图参数映射到内联清单快捷方式完成。有关详细信息，请参阅使用快捷方式意图完成。

属性

android:name：要与内联清单快捷方式完成关联的内置意图参数的名称。该名称应为内置意图参数的叶子级字段（例如，menuItem.name）。

<slice>

使 Google 助理能够将与此功能匹配的查询结果嵌入为 Android 切片。有关详细信息，请参阅将应用操作与 Android 切片集成。

快捷方式架构

下表描述了用于启用应用操作功能的快捷方式元素的属性。包含标签时，除非标记为“可选”，否则其所有属性都是必需的。

Shortcuts.xml 标签	包含于	属性
`<shortcut>`	`<shortcuts>`	`android:shortcutId` `android:shortcutShortLabel` `android:shortcutLongLabel`（可选） `android:icon`（可选）
`<intent>`	`<shortcut>`	`android:action` `android:targetClass`（可选） `android:targetPackage`（可选） `android:data`（可选）
`<capability-binding>`	`<shortcut>`	`android:key`
`<parameter-binding>`	`<capability-binding>`	`android:key`（可选） `android:value`
`<extra>`	`<shortcut>`	`android:name`（可选） `android:value` 仅适用于枚举参数匹配。

快捷方式架构描述

本节描述快捷方式架构元素。

<shortcut>

在shortcuts.xml中定义的 Android<shortcut>，其中包含与应用操作相关的某些属性。shortcutShortLabel和shortcutLongLabel字段的字符串值通过 APK 的字符串资源进行引用。

属性

android:shortcutId：此快捷方式的标识符。
android:shortcutShortLabel：表示简短快捷方式短语的字符串资源。例如，"@string/callDavidShort"表示值“呼叫 David”。
android:shortcutLongLabel：表示较长快捷方式短语的字符串资源。例如，"@string/callDavidLong"表示值“向 David 打电话”。

<intent>

与此快捷方式关联的 Android 意图。当用户使用语音或触摸启动此快捷方式时，将执行此 intent。

shortcut 意图属性与 capability intent 属性相同。

<capability-binding>

将一个 shortcut 与 App Actions capability 关联。将此元素添加到 shortcut 中，可以通过 Assistant 实现语音执行。

属性

android:key：此 shortcut 绑定的 capability 的 android:name 属性。例如，actions.intent.CREATE_TAXI_RESERVATION。

<parameter-binding>

可选属性，用于将 shortcut 与 App Actions capability 的单个参数关联。如果为 shortcut 定义了 parameter-binding，则可以使用该快捷方式为 BII 参数提供内联清单实体。有关更多详细信息，请参阅 App Actions 的内联清单。

属性

android:key：要将此快捷方式关联到的 capability BII 参数的名称。例如，foodObservation.aboutFood.name。
android:value：entity 值。这可以是单个 entity 或资源列表。

<extra>

快捷方式的 extra 包捆绑数据。**sameAs** 是与 App Actions shortcut 元素相关联的唯一数据。**sameAs** URL 指的是明确标识实体的参考网页。仅当意图参数类型是 schema.org/Enumeration 的子类型时，才用于指定枚举值。对于类型为 schema.org/Enumeration 的子类型（例如：MealTypeBreakfast）的参数字段，此属性是必需的。

属性

android:key：App Actions 支持的值为：sameAs
android:value：sameAs URL 值

有关更多详细信息，请参阅匹配枚举参数值。

意图执行选项

您可以在 <capability> 中定义 intent 元素，以声明 Assistant 如何响应或执行与该功能匹配的用户语音命令。有多种方法可以配置 intent 如何在您的应用中启动执行目标，具体取决于您的应用导航结构。

以下执行选项可用

**显式意图**：通过为 intent 定义 targetClass 和 targetPackage 属性来启动特定的应用组件。这是推荐的 App Actions 执行方法。
**深度链接**：通过在 intent 元素中定义 <url-template> 标记来使用 Android 深度链接启动应用目标。如果您的应用导航已经依赖于深度链接，则此方法很有用。
**意图数据**：您可以在 intent android:data 属性中提供执行 URI。如果在 intent 中也定义了该标记，则此字段将被 <url-template> 数据覆盖。

参数数据和匹配

默认情况下，Assistant 会将从用户查询中提取的 BII 参数作为 capability 中定义的 Android intent 的 extra 数据发送到您的应用。

或者，您可以在 capability 中声明一个 <url-template> 标记，其中包含动态参数的占位符。此模板使用应用链接 URL、自定义方案或基于意图的 URL 映射到您的一个 Android 活动。

使用意图额外数据

以下示例演示了为 capability 执行定义的显式意图

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

根据上述示例，对于类似“嘿 Google，从 ExampleApp 订购一杯拿铁”的用户查询，应用会收到一个调用组件的 intent：targetPackage、targetClass。该组件会收到一个额外数据，其中 key = ”menu”，value = ”latte”。

使用 URL 模板进行 Android 深度链接

如果您的应用已经能够处理带有动态参数的应用链接 URL，则可以在 intent 中定义 <url-template> 以生成用于执行的 Android 深度链接。以下示例定义了 <url-template>

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

根据上述示例，对于类似“嘿 Google，从 ExampleApp 订购一杯拿铁”的用户查询，应用会收到生成的 URL：“myapp://order?menu=latte”。

要将 BII 参数映射到 URL 中的位置，可以使用 <parameter> 标记的 android:name 属性。此属性对应于您想要使用用户信息替换的 URL 模板中的 android:key 值。android:key 值必须存在于您的 <url-template> 中，并用花括号 ({}) 括起来。

匹配枚举参数值

某些 BII 参数会向您的执行意图提供枚举值，例如，RECORD_FOOD_OBSERVATION BII 的支持的文本值。对于这些参数，Assistant 会将用户的查询（“早餐”）与 sameAs 值与枚举模式 URL (https://schema.googleapis.com/MealTypeBreakfast) 匹配的实体进行匹配。要将枚举值与支持的 entity 关联，请在您的 shortcut 中声明一个 sameAs 关联。以下示例演示了内联实体快捷方式的 sameAs 关联

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

在上述示例中，如果 RECORD_FOOD_OBSERVATION 功能触发了“早餐”餐类型的匹配，则会将以下额外数据与执行 intent 一起发送

key = "for_meal"
value = "meal_breakfast"

功能

以下 App Actions 功能在 shortcuts.xml 中可用。

App Actions 的内联清单

对于某些 BII 参数，快捷方式可用于将实体提取引导到 shortcuts.xml 中指定的一组支持实体，称为内联清单。有关详细信息，请参阅内联清单。

App Actions 的 Web 清单

对于某些 BII，您可以使用 Web 清单作为生成执行 URL 的方法。Web 清单使用您的网站发现 App Action 执行的 URL。当您拥有强大的网络存在并且您的应用内深度链接围绕公开可用的网络内容进行组织时，此功能最有用。

有关详细信息，请参阅 Web 清单。

自定义意图

可以在 shortcuts.xml 中声明自定义意图，以启用应用中与可用 BII 不匹配的功能的语音功能。虽然功能类似于 BII 定义，但自定义意图需要在 shortcuts.xml 中添加两个额外属性

app:queryPatterns：声明自定义意图的不同查询模式的数组资源。
android:mimeType：自定义意图的参数类型。对于 BII，此字段不是必需的，因为参数类型是已知的。对于自定义意图参数，必须声明支持的语义类型。

有关更多详细信息，请参阅自定义意图。

创建 shortcuts.xml

概述

静态快捷方式

功能架构

功能架构描述

<capability>

<intent>

<url-template>

<extra>

<parameter>

<data>

<shortcut-fulfillment>

<parameter>（对于<shortcut-fulfillment>）

<slice>

快捷方式架构

快捷方式架构描述

<shortcut>

<intent>

<capability-binding>

<parameter-binding>

<extra>

意图执行选项

参数数据和匹配

使用意图额外数据

使用 URL 模板进行 Android 深度链接

匹配枚举参数值

功能

App Actions 的内联清单

App Actions 的 Web 清单

自定义意图

<parameter>（对于`<shortcut-fulfillment>`）