添加能力 (capability)

shortcuts.xml 中的能力可让您声明用户启动应用时可以执行的操作类型,并直接跳转到相应操作来执行特定任务。例如,Google 助理的与应用有关的 Action 通过使用能力使开发者可将应用内功能扩展到内置 intent (BII),从而让用户能够使用语音指令激活和控制这些功能。能力包含操作的名称和 intent(用于定位到解析用户 intent 的应用中的目的地)。

在 shortcuts.xml 中定义能力

您可以在 Android 应用开发项目的 shortcuts.xml 资源文件中定义 capability 元素。如需定义 capability 元素,请执行以下操作:

  1. 按照创建静态快捷方式中的说明创建 shortcuts.xml 资源。
  2. 接下来,将以下必需信息添加到能力中:

    • 能力名称:您希望应用支持的操作。如需了解需要能力定义的功能,请参阅组件文档。支持与应用有关的 Action 语音的指令会使用 BII Action ID 作为能力名称(位于内置 intent 参考文档中)。例如,GET_THING BII 会将其 Action ID 列为 actions.intent.GET_THING

    • 应用目的地:应用中的目的地,操作启动该目的地来执行用户请求。使用嵌套在 capability 中的 intent 元素定义应用目的地。

    • 参数映射:每个 intent 可能包含要作为 intent 的 extra 数据传递的参数。例如,每个与应用有关的 Action BII 都包括表示用户通常在触发 BII 的查询中提供的信息的字段。

以下示例演示了 shortcuts.xmlactions.intent.START_EXERCISE 的能力定义,该 BII 使用户能够通过 Google 助理使用语音指令在健身应用中开始锻炼:

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.START_EXERCISE">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.sampleApp"
      android:targetClass="com.example.sampleApp.ExerciseActivity">
      <parameter
        android:name="exercise.name"
        android:key="exerciseType"/>
    </intent>
  </capability>
</shortcuts>

在上例中,<capability> android:name 属性引用了 START_EXERCISE BII。如果用户通过向 Google 助理发出指令“Ok Google,启动 ExampleApp,开始跑步”来调用此 BII,Google 助理会使用嵌套 intent 元素中提供的信息执行用户请求。此示例中的 intent 定义了以下详细信息:

  • android:targetPackage 为此 intent 设置目标应用软件包。
  • android:targetClass 字段指定目的地 activity:com.example.sampleApp.ExerciseActivity
  • intent parameter 声明对内置 intent 参数 exercise.name 的支持,以及如何将从用户处收集的参数值作为 intent 中的 extra 数据进行传递。

将快捷方式与能力相关联

定义某项能力后,您可以通过将静态快捷方式或动态快捷方式与该能力相关联来扩展其功能。快捷方式如何关联到 capability 取决于要实现的功能以及用户请求中包含的实际字词。例如,设想一个场景,在该场景中,用户向 Google 助理发出指令“Ok Google,启动 ExampleApp,开始跑步”,开始在您的健身跟踪应用中跟踪跑步情况。Google 助理可以使用快捷方式启动一个 capability 实例,该实例为 exercise.name 参数定义有效的“run”运动实体。

如需详细了解如何将快捷方式和与应用有关的 Action 相关联,请参阅与应用有关的 Action 概览