创建 shortcuts.xml

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

Assistant 使用自然语言处理从用户查询中提取参数。内置 intent 参考资料列出了每个 BII 能够从相关用户查询中提取的字段。例如，如果用户通过说出“Hey Google, Ask ExampleApp what did I eat for Lunch last Friday”来调用应用中的 [actions.intent.GET_FOOD_OBSERVATION][] capability，Assistant 会从用户请求中提取以下 BII 参数：

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

Assistant 将 BII 参数传递给 capability 中定义的 fulfillment intent。可以在一个 capability 中定义一个或多个 intent 元素，以适应用户调用 BII 的不同方式。例如，您可以定义一个需要上述示例中两个 BII 参数的 fulfillment intent。然后，您可以定义第二个 intent，它只需要一个 BII 参数 foodObservation.forMeal，用于报告特定日期的所有膳食，例如“Hey Google, Ask ExampleApp what did I eat for Lunch.”

概览

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

在应用的清单文件 (AndroidManifest.xml) 中，找到 intent 过滤器设置为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 activity。
使用 Activity 中的 <meta-data> 标记在 AndroidManifest.xml 中添加对 shortcuts.xml 的引用，该 Activity 具有 MAIN 和 LAUNCHER 的 intent 过滤器，如下所示：
```
<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 元素，以扩展 capability 的功能。静态快捷方式会在您将发布版本上传到 Google Play 管理中心时被 Assistant 提取。由于静态快捷方式只能通过创建新版本来创建和更新，因此它们最适用于突出显示应用中的常见 activity 和内容。

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

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

这些快捷方式包含 intent、shortLabel 和 longLabel 属性，使其能够作为主动界面（例如 Assistant 或长按 Android 启动器上的应用图标时）中的芯片被建议和实现。通过使用 <capability-binding> 标记将其与 capability 相关联，操作快捷方式还可以用作下方详述的实体快捷方式。
实体快捷方式。实体快捷方式提供了一系列受支持的参数值，用于语音查询实现 capability。例如，一个实体快捷方式包含一系列运动类型（“徒步”、“跑步”等），并绑定到 START_EXERCISE capability 的 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 Slices

功能架构说明

本部分介绍 capability 架构元素。

<capability>

capability 定义您的应用支持的 App Action intent。您 shortcuts.xml 文件中的每个 <capability> 元素都必须提供至少一个 <intent> 来处理操作的实现。

属性

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

<intent>

Android intent 元素，定义如何使用应用内功能实现用户查询。开发者可以在 capability 中提供多个 <intent> 标记。Assistant 会尝试使用 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 用于实现。如果参数不可用，Assistant 会尝试使用为 capability 定义的下一个 intent 来实现用户查询。

<shortcut-fulfillment>

指定使用为指定参数的内联库存快捷方式中定义的 intent 来实现。有关详细信息，请参阅使用快捷方式 intent 实现。

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

可选属性，用于将单个 BII 参数映射到内联库存快捷方式实现。有关详细信息，请参阅使用快捷方式 intent 实现。

属性

android:name：要与内联库存快捷方式实现关联的 BII 参数的名称。该名称应为 BII 参数的叶级字段（例如，menuItem.name）。

<slice>

使 Assistant 能够将匹配此 capability 的查询结果嵌入为 Android Slice。有关详细信息，请参阅将 App Actions 与 Android Slices 集成。

快捷方式架构

下表描述了用于启用 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 中定义的 Android <shortcut>，具有与 App Actions 相关的某些属性。shortcutShortLabel 和 shortcutLongLabel 字段的字符串值通过 APK 的字符串资源引用。

属性

android:shortcutId：此快捷方式的标识符。
android:shortcutShortLabel：表示简短快捷方式短语的字符串资源。例如，"@string/callDavidShort" 表示值“Call David.”
android:shortcutLongLabel：表示长快捷方式短语的字符串资源。例如，"@string/callDavidLong" 表示值“Make an audio call to David.”

<intent>

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

shortcut intent 属性与 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 指向明确标识实体的参考网页。仅当 intent 参数类型是 schema.org/Enumeration 的子类型时，才用于指定枚举值。对于类型是 schema.org/Enumeration 子类型的参数字段（例如：MealTypeBreakfast），它是必需的。

属性

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

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

Intent 实现选项

您在 <capability> 中定义 intent 元素，以声明 Assistant 如何响应或实现与该功能匹配的用户语音命令。根据您的应用导航结构，有多种方式可以配置 intent 如何启动应用中的实现目标。

以下是可用的实现选项：

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

参数数据和匹配

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

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

使用 intent Extras

以下示例演示了为 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>

根据上述示例，对于“Hey Google, start my run”之类的用户查询，应用会收到一个调用组件的 intent：targetPackage、targetClass。该组件会收到一个 Extra，其中 key = "exercise"，value = "Running"。

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

根据上述示例，对于“Hey Google, start my run”之类的用户查询，应用会收到生成的 URL：“myapp://start?exercise=Running”。

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

匹配枚举参数值

某些 BII 参数向您的实现 intent 提供枚举值，例如 RECORD_FOOD_OBSERVATION BII 的支持文本值。对于这些参数，Assistant 会将用户的查询（“Breakfast”）与 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 capability 触发了“breakfast”餐食类型的匹配，则以下 Extra 会随 fulfillment intent 发送：

key = "for_meal"
value = "meal_breakfast"

功能

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

App Actions 的内联库存

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

自定义 intent

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

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

有关详细信息，请参阅自定义 intent。

创建 shortcuts.xml 利用收藏夹保持井然有序 根据您的偏好保存和分类内容。

概览

静态快捷方式

功能架构

功能架构说明

<capability>

<intent>

<url-template>

<extra>

<parameter>

<shortcut-fulfillment>

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

<slice>

快捷方式架构

快捷方式架构说明

<shortcut>

<intent>

<capability-binding>

<parameter-binding>

<extra>

Intent 实现选项

参数数据和匹配

使用 intent Extras

将 URL 模板用于 Android 深层链接

匹配枚举参数值

功能

App Actions 的内联库存

自定义 intent

创建 shortcuts.xml

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