创建 shortcuts.xml

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

Google 助理使用自然语言处理技术从用户查询中提取参数。内置 Intent 参考文档中列出了每个 BII 能从关联的用户查询中提取的字段。例如，如果用户通过说出“Hey Google，问问 ExampleApp 我上周五中午吃了什么”调用您应用中的 [actions.intent.GET_FOOD_OBSERVATION][] capability，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。然后，可以再定义一个 intent，该 intent 只需要单个 BII 参数 foodObservation.forMeal，当用户提出更简单的请求（例如“Hey Google，问问 ExampleApp 我今天中午吃了什么”）时，它会报告特定日期的所有餐食。

概览

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

1. 在应用的清单文件 (AndroidManifest.xml) 中，找到 intent 过滤器设为 android.intent.action.MAIN 操作和 android.intent.category.LAUNCHER 类别的 activity。

2. 使用同时具有针对 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 的内嵌目录。

capability 架构

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

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 模板规范。

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

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

<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 元素的属性。添加标记时，需要提供除标记为“可选”的属性之外的所有属性。

快捷方式架构说明

本部分介绍 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>

根据以上示例，对于诸如“Hey Google，开始跑步”之类的用户查询，应用会收到调用以下组件的 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，开始跑步”之类的用户查询，应用会收到生成的网址：“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。