此页面由 Cloud Translation API 翻译。

创建 shortcuts.xml

确定要实现的应用内功能和对应的内置 intent (BII) 后，需要在 shortcuts.xml 资源文件中定义一个 capability 元素来声明您的功能支持的 BII。通过将 BII 声明为 capability，可在应用中注册对该语义 intent 的支持，并使用 Google 助理实现该 intent 的语音查询执行方式。

Google 助理使用自然语言处理技术从用户查询中提取参数。内置 Intent 参考文档中列出了每个 BII 能从关联的用户查询中提取的字段。例如，如果用户通过以下方式调用您的应用中的 [actions.intent.GET_FOOD_OBSERVATION][] capability：说：“Hey Google, Ask ExampleApp 我上周五午餐吃了什么”，Google 助理从用户请求中提取以下 BII 参数：

foodObservation.forMeal =“https://schema.googleapis.com/MealTypeLunch”
foodObservation.startTime =“2024-09-06T00:00:00”
foodObservation.endTime = "2024-09-06T23:59:59"

Google 助理会将这些 BII 参数传递给 capability 中定义的执行方式 intent。可以在一个 capability 中定义一个或多个 intent 元素来适应用户调用 BII 的不同方式。例如，可以定义一个需要用到上述示例中的两个 BII 参数的执行方式 intent。然后，您可以定义需要单个 BII 的第二个 intent 参数 foodObservation.forMeal，用于报告特定日期的所有餐点，例如“Hey Google，Ask ExampleApp 我午餐吃了什么”。

概览

可以按以下方式配置与应用有关的 Action：在应用项目的 res/xml 目录中放置一个 shortcuts.xml 文件，然后在应用清单中创建对该 shortcuts.xml 的引用。可以按以下步骤在应用清单中添加对 shortcuts.xml 的引用：

在应用的清单文件 (AndroidManifest.xml) 中，找到 intent 过滤器设为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 activity。
使用同时具有针对 MAIN 和 LAUNCHER 的 intent 过滤器的 Activity 中的 <meta-data> 标记，在 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 中定义与应用有关的 Action 的 capability 时出现编译错误。如需了解详情，请参阅 Android Jetpack 使用入门。

静态快捷方式

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

可以通过静态快捷方式启用以下与应用有关的 Action 功能：

capability 快捷方式。这类快捷方式可用于启动包含预定义 intent 参数值的 capability 实例。例如，可以声明一个应用快捷方式“Start a run”，该快捷方式会在您的健身应用中调用 START_EXERCISE BII capability。

这些快捷方式包含 intent、shortLabel 和 longLabel 属性，使其可以在主动 Surface（例如 Google 助理，或长按 Android 启动器上的应用图标时）中作为条状标签建议和执行。action 快捷方式也可用作 entity 快捷方式（详见下文），只需使用 <capability-binding> 标记将其与 capability 关联即可。
entity 快捷方式。entity 快捷方式为 capability 的语音查询执行方式提供受支持的参数值列表。例如，一个带有一系列运动类型（“hike”“run”等）的 entity 快捷方式绑定到 START_EXERCISE capability 的 exercise.name BII 参数。如果用户话语与某个 entity 匹配，系统会将 shortcutId ID 而不是原始用户查询值传递给 intent。

Entity 快捷方式不会定义 intent、shortLabel 或 longLabel 属性，因此不会在主动 Surface 上建议。如需了解详情，请参阅与应用有关的 Action 的内嵌目录。

注意：声明为 entity 快捷方式的静态快捷方式会被 LauncherApps API 丢弃，这意味着它们适用于 Android 启动器。

capability 架构

下表列出了 shortcuts.xml 中 capability 元素的与应用有关的 Action 的架构。添加标记时，需要提供除标记为“可选”的属性之外的所有属性。

Shortcuts.xml 标记	包含于	属性
`<capability>`	`<shortcuts>`	`android:name` `app:queryPatterns`（仅适用于自定义 intent）
`<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`（仅适用于自定义 intent） `android:required`（可选） `app:shortcutMatchRequired`（可选）
`<shortcut-fulfillment>`	`<capability>`	仅适用于内嵌目录
`<parameter>`	`<shortcut-fulfillment>`	`android:name`
`<slice>`	`<capability>`	仅适用于 Android Slice

capability 架构说明

本部分介绍 capability 架构元素。

<capability>

capability，用于定义应用支持的与应用有关的 Action intent。shortcuts.xml 文件中的每个 <capability> 元素都必须至少提供一个 <intent> 才能处理相应操作的执行方式。

属性：

android:name：内置 intent 操作 ID（例如， [actions.intent.GET_FOOD_OBSERVATION][]）。如需查看支持的内置 intent，请参阅内置 intent 参考文档。
app:queryPatterns：用户预期会对此 intent 执行的查询的字符串数组资源。此属性仅适用于自定义 intent，因为 BII 已包含用户表达尝试执行的任务或尝试搜索的信息的常见方式模型。

<intent>

Android intent 元素，用于定义应如何使用应用内功能来执行用户查询。开发者可以在 capability 中提供多个 <intent> 标记。Google 助理会尝试使用 capability 中的第一个 <intent>（已为其提供所有必需参数）来执行用户查询。

属性：

android:action：intent 的 Action 类型。默认为 ACTION_VIEW。
android:targetClass：目标 activity 类，例如："com.example.exercise.ExerciseActivity"
android:targetPackage：包含目标 activity 类的软件包，例如："com.example.exercise
android:data：如果 intent 中声明了 <url-template> 标记，则此字段会被该标记重写。

<url-template>

用于构造要在设备上打开的深层链接 URI 的模板。如果为模板提供了所有必需参数，则可以使用内置 intent 参数展开该模板。如需查看 HTTP 网址模板示例，请参阅关于网址模板的维基百科文章。模板格式遵循 RFC 6570 URI 模板规范。

以下是网址模板值的一些示例：

模板	值	展开值
`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`

如需详细了解如何配置网址模板，请参阅执行方式中的网址模板。

<extra>

定义 intent 的 extra 数据。对于与应用有关的 Action，此字段仅用于为 capability 启用 [前台应用调用][]。

<parameter>

将 BII 参数映射到 intent 参数值。如需了解详情，请参阅参数数据和匹配。

属性：

android:name：要与此 intent 参数关联的 BII 参数的名称。该名称应为该 BII 参数的叶级字段（例如 foodObservation.aboutFood.name）。
android:key：BII 参数值的开发者定义键。例如，可以为 message.recipient.name BII 参数定义 contact_name。
android:mimeType：参数的 mimeType，例如 text/*。只有自定义 intent 的参数需要此字段。
android:required：声明用户查询是否需要包含此参数，以便此 intent 用于执行方式。如果该参数不可用，Google 助理会尝试使用为 capability 定义的下一个 intent 来执行用户查询。

<shortcut-fulfillment>

指定在内嵌目录快捷方式中为指定参数定义的 intent 用于执行方式。如需了解详情，请参阅采用快捷方式 intent 的执行方式。

<parameter>（适用于 `<shortcut-fulfillment>`）

一个可选属性，用于将单个 BII 参数映射到内嵌目录快捷方式执行方式。如需了解详情，请参阅采用快捷方式 intent 的执行方式。

属性：

android:name：要与内嵌目录快捷方式执行方式关联的 BII 参数的名称。该名称应为该 BII 参数的叶级字段（例如 menuItem.name）。

<slice>

使 Google 助理能够将匹配此 capability 的查询的结果作为 Android Slice 嵌入。如需了解详情，请参阅将与应用有关的 Action 与 Android Slice 集成。

快捷方式架构

下表列出了用于实现与应用有关的 Action 功能的 shortcut 元素的属性。添加标记时，需要提供除标记为“可选”的属性之外的所有属性。

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 架构元素。

<shortcut>

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

属性：

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

<intent>

与此快捷方式关联的 Android intent。当用户通过语音或触摸启动此快捷方式时，系统就会执行此 intent。

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

<capability-binding>

将 shortcut 关联到与应用有关的 Actioncapability。将此元素添加到 shortcut 可使其可用于使用 Assistant 执行语音指令。

属性：

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

<parameter-binding>

将 shortcut 关联到与应用有关的 Action capability 的单个参数的可选属性。如果为 shortcut 定义了 parameter-binding，则可以使用该快捷方式向 BII 参数提供内嵌目录 entity。如需了解详情，请参阅与应用有关的 Action 的内嵌目录。

属性：

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

<extra>

快捷方式的 extra bundle 数据。sameAs 是和与应用有关的 Action shortcut 元素相关的唯一数据。sameAs 网址指向明确标识该 entity 的参考网页。当且仅当 intent 参数类型是 schema.org/Enumeration 的子类型时，才用于指定枚举值。对于类型为 schema.org/Enumeration 的子类型的参数字段（例如 MealTypeBreakfast），必需提供该属性。

属性：

android:key：与应用有关的 Action 支持的值为：sameAs
android:value：sameAs 网址值

如需了解详情，请参阅匹配枚举参数值。

intent 执行方式选项

可以在 <capability> 中定义 intent 元素，以声明 Google 助理如何响应或执行与该 capability 匹配的用户语音指令。可以通过多种方式配置 intent 在应用中启动执行方式目标页面的方式，具体取决于应用的导航结构。

可以使用以下执行方式选项：

显式 intent：通过为 intent 定义 targetClass 和 targetPackage 属性来启动特定的应用组件。这是与应用有关的 Action 的推荐执行方式。
深层链接：通过在 intent 元素中定义 <url-template> 标记，使用 Android 深层链接启动应用目标页面。如果您的应用导航已经依赖于深层链接，则此方法会很有用。
intent 数据：您可以在 intent android:data 属性中提供执行方式 URI。如果还在 intent 中定义了 <url-template> 标记，则该字段会被该标记的数据重写。

参数数据和匹配

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

或者，您也可以在 capability 中声明 <url-template> 标记（包含动态参数的占位符）。此模板使用应用链接网址、自定义架构或基于 intent 的网址映射到您的其中一个 Android activity。

使用 intent extra

以下示例展示了为 capability 执行方式定义的显式 intent：

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

根据以上示例，对于诸如“Ok Google，从 ExampleApp 订一杯拿铁”之类的用户查询，应用会收到调用以下组件的 intent：targetPackage、targetClass。相应组件通过 key = "exercise"、value = "Running" 接收 extra。

为 Android 深层链接使用网址模板

如果您的应用已经能够处理链接应用的网址，则可以使用动态参数在 intent 中定义 <url-template> 来为执行方式生成 Android 深层链接。以下示例定义了 <url-template>：

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://start{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

以上述示例为例，对于诸如“Hey Google，点拿铁”之类的用户询问 from ExampleApp”中，“该应用将收到生成的网址： “myapp://start?exercise=Running”。

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

匹配枚举参数值

某些 BII 参数会向您的执行方式 intent 提供枚举值，例如 RECORD_FOOD_OBSERVATION BII 的支持的文本值。对于这些参数，Google 助理会将用户的查询（“Breakfast”）与 sameAs 值与枚举架构网址 (https://schema.googleapis.com/MealTypeBreakfast) 匹配的 entity 进行匹配。如需关联受支持的 entity 的枚举值，请在 shortcut 中声明 sameAs 关联。以下示例展示了内嵌 entity 快捷方式的 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 capability 触发了对“breakfast”餐点类型的匹配，则执行方式 intent 会发送以下 extra：

key = "for_meal"
value = "meal_breakfast"

功能

shortcuts.xml 中提供了以下与应用有关的 Action 功能。

与应用有关的 Action 的内嵌目录

对于某些 BII 参数，可以使用快捷方式将 entity 提取引导到 shortcuts.xml 中指定的一组受支持的 entity（称为内嵌目录）。如需了解详情，请参阅内嵌目录。

自定义 intent

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

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

如需了解详情，请参阅自定义 intent。

创建 shortcuts.xml

概览

静态快捷方式

capability 架构

capability 架构说明

<capability>

<intent>

<url-template>

<extra>

<parameter>

<shortcut-fulfillment>

<parameter>（适用于 <shortcut-fulfillment>）

<slice>

快捷方式架构

快捷方式架构说明

<shortcut>

<intent>

<capability-binding>

<parameter-binding>

<extra>

intent 执行方式选项

参数数据和匹配

使用 intent extra

为 Android 深层链接使用网址模板

匹配枚举参数值

功能

与应用有关的 Action 的内嵌目录

自定义 intent

<parameter>（适用于 `<shortcut-fulfillment>`）