内联清单

在为您的 Android 应用实现应用操作时，您可能会发现自己需要处理主题变化的请求。例如，假设您的健身应用实现了 START_EXERCISE 内置意图 (BII)，以允许用户通过询问助手以下内容来启动各种锻炼：“嘿 Google，在示例应用中开始跑步”。

实现此意图需要您的请求匹配逻辑来处理每种类型的锻炼，包括“慢跑”、“冲刺”或“竞赛”等变体。随着支持的锻炼增加，此逻辑很快就会变得繁琐。

对于支持的 BII（如 START_EXERCISE），您可以通过使用内联清单来避免这种复杂的匹配逻辑。内联清单是在 shortcuts.xml 中定义的一组静态 Android 快捷方式，代表您应用中的功能和内容。

每个快捷方式都包含一个项目标识符和一个同义词列表，这些同义词代表用户可能用来指代该项目的各种方式。在调用期间，BII 会将用户提供的 BII 参数与同义词列表进行比较。当找到匹配项时，BII 参数将更新为匹配快捷方式的项目标识符。

内联清单允许 Google 助手简化应用操作调用期间提供给您的应用的 BII 参数值。

内联清单充当 BII 参数的查找表，使用您定义的项目标识符来表达用户指代应用中功能或内容的各种方式。它们通过让您的实现预测来自 BII 参数的项目标识符来简化您的应用的请求匹配逻辑。

Inline inventory user flow diagram — **图 1.** 使用内联清单来解释用户提供的锻炼名称以获取应用中支持的锻炼类型的 `START_EXERCISE` 功能的流程图。

限制和替代方案

内联清单快捷方式具有以下限制

快捷方式限制：每个应用最多可以定义 1,000 个内联清单快捷方式。
同义词限制：每个内联清单快捷方式最多可以包含 20 个同义词值。
静态定义：内联清单快捷方式在 shortcuts.xml 中静态声明，只能通过发布新版本的应用来为您的用户更新。

鉴于需要静态配置，内联清单最适合将变化不频繁的非个性化应用信息扩展到助手，例如菜单项、公交路线或饮料大小。对于其他类型的内容，请考虑以下替代方案

网络清单： 允许助手在将用户查询与支持的应用内容标识符匹配时查询公共网络内容。网络清单查询在调用期间实时发生，允许您将产品目录、社交媒体帖子和其他频繁更新的内容扩展到助手。
动态快捷方式： 将个性化应用内容的清单扩展到助手。动态快捷方式允许用户快速重播常见操作，例如从食品订购应用中重新订购他们最喜欢的饮料，或在笔记应用中调出购物清单。

创建内联清单

内联清单通过为助手提供一种便捷的方式来将用户请求应用内容和功能的不同方式转换为应用预期的可预测标识符来简化开发。例如，假设您的应用提供用户可以使用语音启动的不同锻炼，并且您的应用期望用户对同一种锻炼类型发出以下请求

嘿 Google，在示例应用中开始跑步。
嘿 Google，在示例应用中开始慢跑。

在您的内联清单快捷方式中，您将 shortcutId 设置为 "CARDIO_RUN"（您的应用预期的锻炼标识符）。然后，您指定“跑步”和“慢跑”作为与 shortcutId 关联的同义词。然后，当用户使用前面的查询触发您的应用操作时，助手在生成实现意图时将使用标识符 "CARDIO_RUN" 作为 BII 参数。

来自示例 app/res/shortcuts.xml 文件的以下代码片段实现了此案例

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

在前面的示例中，内联清单 shortcut 在 <capability-binding> 元素内声明一个 <parameter-binding> 标签，将其绑定到在 <capability> 中定义的 exercise.name BII 参数。

字符串数组资源 @array/run_names 在 res/values/arrays.xml 中指定助手识别并映射到 "CARDIO_RUN" 项目 ID 的同义词列表

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

如果为功能提供了<url-template>，则匹配值的shortcutId 将插入到生成的 URL 中与参数对应的占位符中。以下代码来自示例app/res/shortcuts.xml 文件，实现了此案例。

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

在之前的示例中，Assistant 会生成以下完整深层链接：myapp://workout?exercise=CARDIO_RUN。

使用快捷方式意图进行完整操作

默认情况下，快捷方式会将匹配的内联清单值的shortcutId 提供给快捷方式绑定到的capability 的intent（在快捷方式的<capability-binding> 标签中声明）。您可以选择指定快捷方式本身中定义的intent 用于完整操作，方法是向capability 添加<shortcut-fulfillment>标签。

以下代码来自示例app/res/shortcuts.xml 文件，实现了快捷方式完整操作。

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

在前面的示例中，如果用户查询与exercise.name 参数的内联清单值匹配，则<shortcut-fulfillment> 标签指定使用绑定快捷方式的intent 进行完整操作。

用于打开应用功能 BII 的内联清单

虽然内联清单通常是支持它的 BII 的可选功能，但对于某些 BII（如OPEN_APP_FEATURE）是必需的。这个常用的 BII 允许用户使用 Assistant 深度链接到特定的应用功能。打开应用功能 BII 需要应用功能名称的内联清单，以便在将用户深度链接到您的应用之前验证用户请求的功能是否存在。

以下代码来自示例app/res/shortcuts.xml 文件，该文件使用代表应用订单状态功能的单个快捷方式实现了此 BII。

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

res/values/arrays.xml 中的字符串数组资源@array/order_status_names 指定了此功能的同义词列表。

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

有了前面的功能，Assistant 就可以完成同一个功能的各种短语。

“嘿 Google，在我的示例应用中显示我的订单状态。”
“嘿 Google，在我的示例应用中显示我的订单。”
“嘿 Google，在我的示例应用中显示我的订单历史记录。”

测试内联清单

通过检查 Assistant 在完成相关的应用操作功能时提供给您的应用程序的 BII 参数值来测试您的清单。内联清单的工作原理是将用户提供的清单绑定 BII 参数的值替换为匹配的内联清单快捷方式的shortcutId。

例如，START_EXERCISE BII 功能可以使用内联清单将用户提供的 BII 参数“run”转换为其对应的运动 ID"CARDIO_RUN"。

使用Google Assistant 插件可以在测试设备上的 Assistant 中预览您的内联清单应用操作。按照以下步骤使用插件测试您的清单：

配置 BII 功能的清单绑定参数及其与内联清单关联的同义词值。
触发插件中的 BII，在您的测试设备上调用它。
检查 Assistant 在应用操作完成过程中提供给您的应用程序的最终参数值。