内联清单

当您为 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` 功能流程图。

限制和替代方案

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

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

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

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

创建内联清单

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

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

在前面的示例中，助理生成实现深层链接 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 允许用户使用语音助手深度链接到特定的应用功能。打开应用功能 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>

有了前面的功能，语音助手就可以为同一功能执行各种短语

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

测试内联清单

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

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

Google 助理插件允许您在测试设备上的语音助手上预览您的内联清单应用操作。按照以下步骤使用插件测试您的清单

使用与您的内联清单关联的同义词值配置 BII 功能的清单绑定参数。
从插件触发 BII，在您的测试设备上调用它。
检查语音助手在应用操作执行期间提供给您应用的结果参数值。