此页面由 Cloud Translation API 翻译。

设计互动式卡片或对话框

本页介绍了如何向卡片或对话框消息添加微件和界面元素让用户可以与您的 Google Chat 应用互动，例如点击某个按钮或提交信息。

使用卡片构建器设计和预览聊天应用的 JSON 卡片消息：

打开卡片制作工具

前提条件

Google Workspace 账号可访问 Google Chat。

一款已发布的 Chat 应用。要构建 Chat 应用，关注此内容快速入门。

添加按钮

通过 ButtonList widget 会显示一组按钮。按钮可以显示文字、或同时添加文字和图标每个 Button 支持 OnClick 操作用户点击该按钮时发生的情况例如：

使用以下应用打开超链接： OpenLink, 以便为用户提供更多信息。
运行 action 运行自定义函数，例如调用 API。

为了确保无障碍，按钮支持替代文本。

添加可运行自定义函数的按钮

下面是一个卡片，由带有两个按钮的 ButtonList widget 组成。只需点击一下按钮，即可在新标签页中打开 Google Chat 开发者文档。通过另一个按钮会运行一个名为 goToView() 的自定义函数，并将 viewType="BIRD EYE VIEW" 参数。

添加一个带有自定义颜色和已停用按钮的按钮

您可以通过设置 "disabled": "true" 禁止用户点击按钮。

以下代码显示了一张卡片，该卡片由一个 ButtonList widget 组成，其中包含两个按钮。一个按钮使用 Color 字段自定义按钮的背景 color 决定。另一个按钮可通过 Disabled 字段停用，该字段显示可以防止用户点击按钮并执行函数。

添加带图标的按钮

以下代码显示了一张卡片，该卡片由一个 ButtonList widget 和两个图标组成 Button widget。一个按钮使用 knownIcon 字段以显示 Google Chat 的内置电子邮件图标。另一个按钮使用 iconUrl 字段可显示自定义图标 widget。

添加带有图标和文本的按钮

以下代码显示了一张由 ButtonList widget 组成的卡片，用于提示用户发送电子邮件。第一个按钮显示一个电子邮件图标，第二个按钮会显示文字。用户可以点击图标或文本按钮运行 sendEmail 函数。

添加可选择的界面元素

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

SelectionInput widget 支持建议，以帮助用户输入制服以及更改时操作， Actions 选择输入字段（例如用户选择或取消选择某项内容。

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

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

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

添加复选框

下面会显示一个对话框，要求用户指定是职业联系人和/或个人联系人，并且使用 SelectionInput widget 使用复选框：

添加单选按钮

下面会显示一个对话框，要求用户指定某个 SelectionInput 微件使用单选按钮：

添加开关

下面会显示一个对话框，要求用户指定使用 SelectionInput widget 使用开关：

下面会显示一个对话框，要求用户指定某个 SelectionInput 微件使用下拉菜单：

下面会显示一个对话框，要求用户选择联系人执行以下操作：

为多选菜单使用数据源

以下部分介绍了如何使用多选菜单填充数据来自动态来源（例如 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 项。

如需自动补全项，请创建一个用于查询外部数据的函数 source 和返回项；每当用户在多选菜单中输入内容时，它便会返回相应项。通过函数必须执行以下操作：

传递表示用户与菜单的互动的事件对象。
确定互动事件的 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
            },
          ]
        }
      }
    }
  };
}

添加一个供用户输入文本的字段

TextInput widget 提供了一个字段，供用户输入文本。通过微件支持提供建议，以帮助用户输入统一的数据，也就是 Actions 在文本输入字段发生变化（例如用户添加或删除文本。

如果您需要从用户那里收集抽象或未知数据，请使用此 TextInput widget。要从用户那里收集定义的数据，请使用 SelectionInput 微件。

要处理用户输入的文本，请参阅接收表单数据。

以下是由 TextInput widget 组成的卡片：

让用户选择日期和时间

通过 DateTimePicker widget 允许用户输入日期和/或时间。用户也可以使用该选择器选择日期和时间。如果用户输入日期或时间无效，选择器就会显示错误，以提示用户输入信息。

要处理用户输入的日期和时间值，请参阅接收表单数据。

下面显示了一张卡片，该卡片包含三种不同类型的 DateTimePicker widget：

验证输入到卡片的数据

本页介绍了如何验证输入到卡片的 action 的数据和微件。例如，您可以验证文本输入字段是否包含或包含一定数量的字符。

设置操作所需的微件

在卡片的 action 中，将操作所需的 widget 名称添加到其 requiredWidgets 列表中。

如果此处列出的任何微件在调用此操作时都没有值，表单操作提交就会被取消。

为操作设置 "all_widgets_are_required": "true" 后，所有 widget 因为此操作需要该卡中的密码。

在多选模式下设置 `all_widgets_are_required` 操作

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "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
              }
            ]
          }
        }
      ]
    }
  ]
}

在 dateTimePicker 中设置 `all_widgets_are_required` 操作

JSON

{
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}

在下拉菜单中设置 `all_widgets_are_required` 操作

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

为文本输入 widget 设置验证

在textInput中微件的验证字段，它可以指定此文本输入 widget。

为文本输入微件设置字符数限制

JSON

{
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}

设置文本输入 widget 的输入类型

JSON

{
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

问题排查

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

虽然 Chat 界面中可能不会显示错误消息，提供描述性错误消息和日志数据，以帮助您修正错误启用 Chat 应用的错误日志记录时。如需观看方面的帮助，请参阅排查并修正 Google Chat 错误。

设计互动式卡片或对话框

前提条件

添加按钮

添加可运行自定义函数的按钮

添加一个带有自定义颜色和已停用按钮的按钮

添加带图标的按钮

添加带有图标和文本的按钮

添加可选择的界面元素

添加复选框

添加单选按钮

添加开关

添加多选菜单

为多选菜单使用数据源

来自 Google Workspace 的数据源

JSON

JSON

Google Workspace 以外的数据源

JSON

Apps 脚本

Node.js

添加一个供用户输入文本的字段

让用户选择日期和时间

验证输入到卡片的数据

设置操作所需的微件

在多选模式下设置 `all_widgets_are_required` 操作

JSON

在 dateTimePicker 中设置 `all_widgets_are_required` 操作

JSON

在下拉菜单中设置 `all_widgets_are_required` 操作

JSON

为文本输入 widget 设置验证

为文本输入微件设置字符数限制

JSON

设置文本输入 widget 的输入类型

JSON

问题排查

相关主题

设计互动式卡片或对话框

前提条件

添加按钮

添加可运行自定义函数的按钮

添加一个带有自定义颜色和已停用按钮的按钮

添加带图标的按钮

添加带有图标和文本的按钮

添加可选择的界面元素

添加复选框

添加单选按钮

添加开关

添加下拉菜单

添加多选菜单

为多选菜单使用数据源

来自 Google Workspace 的数据源

JSON

JSON

Google Workspace 以外的数据源

JSON

Apps 脚本

Node.js

添加一个供用户输入文本的字段

让用户选择日期和时间

验证输入到卡片的数据

设置操作所需的微件

在多选模式下设置 all_widgets_are_required 操作

JSON

在 dateTimePicker 中设置 all_widgets_are_required 操作

JSON

在下拉菜单中设置 all_widgets_are_required 操作

JSON

为文本输入 widget 设置验证

为文本输入微件设置字符数限制

JSON

设置文本输入 widget 的输入类型

JSON

问题排查

相关主题

在多选模式下设置 `all_widgets_are_required` 操作

在 dateTimePicker 中设置 `all_widgets_are_required` 操作

在下拉菜单中设置 `all_widgets_are_required` 操作