创建 shortcuts.xml

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

助手使用自然语言处理从用户查询中提取参数。内置意图参考列出了每个 BII 可以从关联的用户查询中提取的字段。例如，如果用户通过说“嘿 Google，问问 ExampleApp 我上周五午餐吃了什么”来调用应用中的 [actions.intent.GET_FOOD_OBSERVATION][] 功能，助手会从用户请求中提取以下 BII 参数：

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

助手会将 BII 参数传递到 capability 中定义的 fulfillment intent。可以在一个功能中定义一个或多个 intent 元素，以适应用户调用 BII 的不同方式。例如，您可以定义一个需要上述示例中两个 BII 参数的 fulfillment intent。然后，您可以定义第二个仅需要一个 BII 参数 foodObservation.forMeal 的意图，该意图报告特定日期的所有餐点，例如“嘿 Google，问问 ExampleApp 我午餐吃了什么”。

概述

您可以使用放置在应用项目 res/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 中定义 App Actions 功能时出现编译错误。详情请参阅 Android Jetpack 入门指南。

静态快捷方式

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

您可以使用静态快捷方式启用以下 App Actions 功能

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

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

Entity 快捷方式不定义 intent、shortLabel 或 longLabel 属性，因此不会在主动界面上建议。详情请参阅 App Actions 的内联清单。

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

功能模式

下表描述了 shortcuts.xml 中 capability 元素的 App Actions 模式。包含标签时，除非标记为“可选”，否则所有属性都是必需的。

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 切片

功能模式说明

本节介绍 capability 模式元素。

<capability>

一个 capability，它定义了您的应用支持的 App 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 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>

定义 intent 的额外数据。对于 App Actions，此字段仅用于为 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 切片。详情请参阅将 App Actions 与 Android 切片集成。

快捷方式模式

下表描述了用于启用 App Actions 功能的 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 中定义的具有与 App Actions 相关的某些属性的 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.START_EXERCISE。

<parameter-binding>

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

属性

android:key：要将此快捷方式关联到的capability BII参数的名称。例如，exercise.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>标签，其中包含动态参数的占位符。此模板使用App Links URL、自定义方案或基于Intent的URL映射到您的一个Android活动。

使用Intent Extras

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

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

根据上述示例，对于类似“嘿，Google，开始我的跑步”的用户查询，应用程序会接收一个调用组件的intent：targetPackage、targetClass。该组件接收一个具有key = "exercise"、value = "Running"的Extra。

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

如果您的应用程序已经能够处理具有动态参数的应用链接URL，则可以在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>

根据上述示例，对于类似“嘿，Google，开始我的跑步”的用户查询，应用程序会收到生成的URL：“myapp://start?exercise=Running”。

要将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功能触发了“早餐”膳食类型的匹配，则会使用以下Extra发送执行intent

key = "for_meal"
value = "meal_breakfast"

功能

shortcuts.xml中提供以下App Actions功能。

App Actions的内联库存

对于某些BII参数，快捷方式可用于将实体提取引导到shortcuts.xml中指定的受支持实体集，称为内联库存。详情请参阅内联库存。

自定义意图

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

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

更多详情，请参阅自定义意图。

创建 shortcuts.xml

概述

静态快捷方式

功能模式

功能模式说明

<capability>

<intent>

<url-template>

<extra>

<parameter>

<shortcut-fulfillment>

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

<slice>

快捷方式模式

快捷方式模式说明

<shortcut>

<intent>

<capability-binding>

<parameter-binding>

<extra>

意图执行选项

参数数据和匹配

使用Intent Extras

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

匹配枚举参数值

功能

App Actions的内联库存

自定义意图

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