此页面由 Cloud Translation API 翻译。

Switch to English

选择输入

SelectionInput widget 提供一组可选择的项，例如复选框、单选按钮、开关或下拉菜单。您可以使用此微件向用户收集已定义和标准化的数据。如需向用户收集未定义的数据，请改用 TextInput widget。

SelectionInput widget 支持建议（可帮助用户输入统一数据）和变化操作（即 Actions），在选择输入字段中发生更改（例如用户选择或取消选择某项）时运行。

聊天应用可以接收和处理所选项的价值。如需详细了解如何使用表单输入，请参阅接收表单数据。

示例

本部分提供了使用 SelectionInput widget 的卡片示例。这些示例使用不同类型的部分输入：

复选框
单选按钮
开关
下拉菜单
多选菜单

示例 1：复选框

以下代码会显示一个对话框，要求用户通过使用复选框的 SelectionInput widget 指定联系人是专业联系人和/或个人联系人：

示例 2：单选按钮

以下代码会显示一个对话框，让用户通过一个使用单选按钮的 SelectionInput widget 指定联系人是专业联系人还是个人联系人：

示例 3：开关

以下代码会显示一个对话框，要求用户通过使用开关的 SelectionInput widget 指定联系人是专业联系人还是个人联系人：

以下代码会显示一个对话框，让用户通过一个使用下拉菜单的 SelectionInput widget 指定联系人是专业联系人还是个人联系人：

下面会显示一个对话框，要求用户从多选菜单中选择联系人：

适用于多选菜单的其他数据源

以下部分介绍了如何使用多选菜单填充来自动态来源（例如 Google Workspace 应用或外部数据源）的数据。

来自 Google Workspace 的数据源

您可以在 Google Workspace 中从以下数据源为多选菜单填充内容：

Google Workspace 用户：您只能填充同一 Google Workspace 组织中的用户。
Chat 聊天室：用户在多选菜单中输入内容时，只能查看和选择其 Google Workspace 组织中所属的聊天室。

如需使用 Google Workspace 数据源，请指定 platformDataSource 字段。与其他选择输入类型不同，您可以省略 SectionItem 对象，因为这些选择项是从 Google Workspace 动态获取的。

以下代码显示了一个多选的 Google Workspace 用户菜单。为了填充用户，选择输入会将 commonDataSource 设置为 USER：

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

以下代码显示了 Chat 聊天室的多选菜单。如需填充空格，选择输入需指定 hostAppDataSource 字段。多选菜单还会将 defaultToCurrentSpace 设置为 true，这会将当前空间设为菜单中的默认选择：

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Google Workspace 以外的数据源

多选菜单也可以填充来自第三方或外部数据源的项。例如，您可以使用多选菜单帮助用户从客户关系管理 (CRM) 系统中的潜在客户列表中进行选择。

如需使用外部数据源，请使用 externalDataSource 字段指定用于从数据源返回项的函数。

为了减少对外部数据源的请求，您可以添加在用户输入菜单内容之前显示在多选菜单中的建议项。例如，您可以为用户填充最近搜索过的联系人。如需填充来自外部数据源的建议内容，请指定 SelectionItem 对象。

以下代码显示了用户可从外部联系人集中的项多选菜单。默认情况下，该菜单会显示一个联系人，并运行 getContacts 函数以从外部数据源检索和填充项目：

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

对于外部数据源，您还可以自动补全用户在多选菜单中开始输入的项。例如，如果用户开始为填充美国城市的菜单输入 Atl，您的 Chat 应用可以在用户结束输入之前自动建议 Atlanta。您最多可以自动填充 100 项。

如需自动填充列表项，您需要创建一个函数，该函数会查询外部数据源，并在每次用户在多选菜单中输入内容时返回相应项。该函数必须执行以下操作：

传递一个表示用户与菜单互动的事件对象。
确定互动事件的 invokedFunction 值与 externalDataSource 字段中的函数匹配。
当函数匹配时，从外部数据源返回建议的项。如需根据用户类型建议商品，请获取 autocomplete_widget_query 键的值。此值表示用户在菜单中输入的内容。

以下代码会自动填充外部数据资源中的项。在前面的示例中，Chat 应用会根据函数 getContacts 的触发时间来建议项目：

Apps 脚本

apps-script/selection-input/on-widget-update.gs

在 GitHub 上查看

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js

在 GitHub 上查看

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

JSON 表示法和字段

JSON 表示法

JSON 表示法
{ "name": string, "label": string, "type": enum (`SelectionType`), "items": [ { object (`SelectionItem`) } ], "onChangeAction": { object (`Action`) }, "multiSelectMaxSelectedItems": integer, "multiSelectMinQueryLength": integer, // Union field `multi_select_data_source` can be only one of the following: "externalDataSource": { object (`Action`) }, "platformDataSource": { object (`PlatformDataSource`) } // End of list of possible types for union field `multi_select_data_source`. }

{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}

字段
`name`	`string` 用于标识表单输入事件中的选择输入的名称。如需详细了解如何使用表单输入内容，请参阅接收表单数据。
`label`	`string` 界面中选择输入字段上方显示的文本。指定有助于用户输入应用所需信息的文本。例如，如果用户从下拉菜单中选择工作工单的紧急程度，则相应的标签可能是“紧急”或“选择紧急程度”。
`type`	`enum (SelectionType)` 在 `SelectionInput` widget 中向用户显示的项的类型。选择类型支持不同类型的互动。例如，用户可以选中一个或多个复选框，但只能从下拉菜单中选择一个值。
`items[]`	`object (SelectionItem)` 可选项的数组。例如，单选按钮或复选框的数组。最多支持 100 项内容。
`onChangeAction`	`object (Action)` 如果已指定，则会在选择发生更改时提交表单。如果未指定，则必须指定一个用于提交表单的单独按钮。如需详细了解如何使用表单输入内容，请参阅接收表单数据。
`multiSelectMaxSelectedItems`	`integer` 对于多选菜单，这是指用户可以选择的最大项数。最小值为 1 项。如果未指定，则默认为 3 项。
`multiSelectMinQueryLength`	`integer` 对于多选菜单，用户在 Chat 应用查询之前输入的文本字符数会自动填充，并在菜单中显示建议的项。如果未指定，则静态数据源默认为 0 个字符，外部数据源默认为 3 个字符。
联合字段 `multi_select_data_source`。仅限 Chat 应用。对于多选菜单，此为用于填充选择项的数据源。 `multi_select_data_source` 只能是下列其中一项：
`externalDataSource`	`object (Action)` 外部数据源，例如关系型数据库。
`platformDataSource`	`object (PlatformDataSource)` 来自 Google Workspace 的数据源。

SelectionType

枚举
`CHECK_BOX`	一组复选框。用户可以选中一个或多个复选框。
`RADIO_BUTTON`	一组单选按钮。用户可以选择一个单选按钮。
`SWITCH`	一组开关。用户可以开启一个或多个开关。
`DROPDOWN`	一个下拉菜单。用户可以从菜单中选择一项。
`MULTI_SELECT`	Chat 应用支持，但 Google Workspace 插件不支持。静态或动态数据的多选菜单。用户可从菜单栏中选择一项或多项。用户还可以输入值来填充动态数据。例如，用户可以开始输入某个 Google Chat 聊天室的名称，而微件会自动建议该聊天室。如需为多选菜单填充内容，您可以使用以下类型的数据源：静态数据：列表项在 widget 中被指定为 `SelectionItem` 对象。最多 100 项内容。 Google Workspace 数据：这些内容使用 Google Workspace 中的数据填充，例如 Google Workspace 用户或 Google Chat 聊天室。外部数据：系统会从 Google Workspace 以外的外部数据源填充内容。如需查看有关如何实现多选菜单的示例，请参阅 `SelectionInput` widget 页面。

SelectionItem

JSON 表示法
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string }

字段
`text`	`string` 用于向用户标识或描述商品的文本。
`value`	`string` 与此商品相关联的值。客户端应将此值用作表单输入值。如需详细了解如何使用表单输入内容，请参阅接收表单数据。
`selected`	`boolean` 默认情况下，项目是否处于选中状态。如果所选项输入仅接受一个值（例如单选按钮或下拉菜单），请仅为一项设置此字段。
`startIconUri`	`string` 对于多选菜单，是在项目的 `text` 字段旁边显示的图标的网址。支持 PNG 和 JPEG 文件。必须是 `HTTPS` 网址。例如 `https://developers.google.com/chat/images/quickstart-app-avatar.png`。
`bottomText`	`string` 对于多选菜单，这是显示在该项的 `text` 字段下方的文本说明或标签。

操作

一个操作，用于描述提交表单时的行为。例如，您可以调用 Apps 脚本脚本来处理表单。如果操作被触发，表单值会发送到服务器。

JSON 表示法
{ "function": string, "parameters": [ { object (`ActionParameter`) } ], "loadIndicator": enum (`LoadIndicator`), "persistValues": boolean, "interaction": enum (`Interaction`) }

字段
`function`	`string` 点击或激活所含元素时要调用的自定义函数。如需查看用法示例，请参阅创建互动卡片。
`parameters[]`	`object (ActionParameter)` 操作参数列表。
`loadIndicator`	`enum (LoadIndicator)` 指定在调用该操作时操作显示的加载指示器。
`persistValues`	`boolean` 指示表单值在操作后是否保留。默认值为 `false`。如果为 `true`，则表单值将在操作触发后保留。如需允许用户在处理操作期间进行更改，请将 `LoadIndicator` 设置为 `NONE`。对于聊天应用中的卡片消息，您还必须将操作的 `ResponseType` 设置为 `UPDATE_MESSAGE`，并使用包含该操作的卡片中的同一 `cardId`。如果为 `false`，则在触发操作时表单值会被清除。如需阻止用户在处理操作期间进行更改，请将 `LoadIndicator` 设置为 `SPINNER`。
`interaction`	`enum (Interaction)` 可选。打开对话框时必填。在响应与用户互动（例如用户点击卡片消息中的按钮）时应执行的操作。如果未指定，应用将通过照常执行 `action`（如打开链接或运行函数）进行响应。通过指定 `interaction`，应用能够以特殊的交互方式做出响应。例如，通过将 `interaction` 设置为 `OPEN_DIALOG`，应用可以打开对话框。指定后，系统不会显示加载指示器。 Chat 应用支持，但 Google Workspace 插件不支持。如果为插件指定此值，系统会删除整个卡，且客户端中不会显示任何内容。

ActionParameter

调用操作方法时提供的字符串参数列表。例如，可以考虑使用三个延后按钮：“立即延后”“延后一天”或“下周延后”。您可以使用 action method = snooze()，在字符串参数列表中传递暂停类型和暂停时间。

如需了解详情，请参阅 CommonEventObject。

JSON 表示法
{ "key": string, "value": string }

字段

字段
`key`	`string` 操作脚本的参数名称。
`value`	`string` 参数的值。

key

string

操作脚本的参数名称。

value

string

参数的值。

LoadIndicator

指定在调用该操作时操作显示的加载指示器。

枚举
`SPINNER`	显示一个旋转图标，表示正在加载内容。
`NONE`	系统不会显示任何内容。

互动

可选。打开对话框时必填。

在响应与用户互动（例如用户点击卡片消息中的按钮）时应执行的操作。

如果未指定，应用将通过照常执行 action（如打开链接或运行函数）进行响应。

通过指定 interaction，应用能够以特殊的交互方式做出响应。例如，通过将 interaction 设置为 OPEN_DIALOG，应用可以打开对话框。

指定后，系统不会显示加载指示器。

Chat 应用支持，但 Google Workspace 插件不支持。如果为插件指定此值，系统会删除整个卡，且客户端中不会显示任何内容。

枚举

INTERACTION_UNSPECIFIED 默认值。action 会照常执行。

枚举
`INTERACTION_UNSPECIFIED`	默认值。`action` 会照常执行。
`OPEN_DIALOG`	打开一个对话框，这是一个基于卡片的窗口化界面，Chat 应用可使用该界面与用户互动。仅适用于 Chat 应用响应卡片消息中的按钮点击操作时。 Google Workspace 插件不支持。如果为插件指定此值，系统会删除整个卡，且客户端中不会显示任何内容。

OPEN_DIALOG

打开一个对话框，这是一个基于卡片的窗口化界面，Chat 应用可使用该界面与用户互动。

仅适用于 Chat 应用响应卡片消息中的按钮点击操作时。

Google Workspace 插件不支持。如果为插件指定此值，系统会删除整个卡，且客户端中不会显示任何内容。

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”或“无法处理您的请求”的消息。有时，Chat 界面不显示任何错误消息，但 Chat 应用或卡片产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，但为 Chat 应用启用错误日志记录功能，您可以借助描述性错误消息和日志数据来修复错误。如需获取查看、调试和修正错误方面的帮助，请参阅排查并修正 Google Chat 错误。

选择输入

示例

示例 1：复选框

示例 2：单选按钮

示例 3：开关

示例 4：下拉菜单

示例 5：多选菜单

适用于多选菜单的其他数据源

来自 Google Workspace 的数据源

JSON

JSON

Google Workspace 以外的数据源

JSON

Apps 脚本

Node.js

JSON 表示法和字段

SelectionType

SelectionItem

操作

ActionParameter

LoadIndicator

互动

问题排查