本页介绍了如何向卡片或对话框消息添加 widget 和界面元素，以便用户可以与您的 Google Chat 应用互动，例如通过点击按钮或提交信息。
使用卡片构建器设计和预览聊天应用的 JSON 卡片消息：
打开卡片构建器前提条件
添加按钮
ButtonList widget 会显示一组按钮。按钮可以显示文本和/或图标。每个 Button 都支持一项 OnClick 操作，该操作在用户点击该按钮时发生。例如：
为了确保无障碍，按钮支持替代文本。
添加可运行自定义函数的按钮
下面是一个卡片，由带有两个按钮的 ButtonList widget 组成。只需点击一下按钮，即可在新标签页中打开 Google Chat 开发者文档。另一个按钮会运行一个名为 goToView() 的自定义函数，并传递 viewType="BIRD EYE VIEW" 参数。
添加一个带有自定义颜色和已停用按钮的按钮
您可以通过设置 "disabled": "true" 禁止用户点击按钮。
以下代码显示了一张卡片，该卡片由一个包含两个按钮的 ButtonList widget 组成。其中一个按钮使用 Color 字段自定义该按钮的背景颜色。另一个按钮会通过 Disabled 字段停用，这样用户就无法点击该按钮并执行函数。
添加带图标的按钮
以下代码显示的卡片由一个 ButtonList widget 和两个图标 Button widget 组成。一个按钮使用 knownIcon 字段显示 Google Chat 的内置电子邮件图标。另一个按钮使用 iconUrl 字段显示自定义图标 widget。
添加带有图标和文本的按钮
以下代码显示了一张卡片，其中包含一个提示用户发送电子邮件的 ButtonList widget。第一个按钮显示电子邮件图标，第二个按钮显示文本。用户可以点击图标或文本按钮来运行 sendEmail 函数。
添加可选择的界面元素
SelectionInput widget 提供了一组可选择的项，例如复选框、单选按钮、开关或下拉菜单。您可以使用此 widget 从用户那里收集已定义的标准化数据。如需从用户那里收集未定义的数据，请改用 TextInput widget。
SelectionInput widget 支持建议（有助于用户输入统一数据）和更改时操作（即 Actions），这些操作会在选择输入字段中发生变化（例如，用户选择或取消选择某个项）时运行。
Chat 扩展应用可以接收和处理所选项目的值。 如需详细了解如何使用表单输入，请参阅接收表单数据。
本部分提供了使用 SelectionInput widget 的卡片示例。这些示例使用不同类型的部分输入：
添加复选框
下面将显示一个对话框，要求用户通过一个使用复选框的 SelectionInput widget 指定联系人是职业联系人、个人联系人，还是两者都是：
添加单选按钮
下面将显示一个对话框，要求用户通过使用单选按钮的 SelectionInput widget 指定联系人是职业联系人还是个人联系人：
添加开关
下面将显示一个对话框，要求用户通过使用开关的 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 脚本
Node.js
添加一个供用户输入文本的字段
TextInput widget 提供了一个字段，用户可以在其中输入文本。该 widget 支持建议（有助于用户输入统一数据）和更改操作（即 Actions，在文本输入字段中发生更改时运行，例如用户添加或删除文本）。
如果您需要从用户那里收集抽象或未知数据，请使用此 TextInput widget。如需从用户那里收集定义的数据，请改用 SelectionInput widget。
要处理用户输入的文本，请参阅接收表单数据。
以下是由 TextInput widget 组成的卡片：
让用户选择日期和时间
借助 DateTimePicker widget，用户可以输入日期和/或时间。用户也可以使用该选择器选择日期和时间。如果用户输入的日期或时间无效，选择器会显示错误，提示用户正确输入信息。
如需处理用户输入的日期和时间值，请参阅接收表单数据。
下图显示了一张卡片，由三种不同类型的 DateTimePicker widget 组成：
验证输入到卡片的数据
本页介绍了如何验证输入到卡片的 action 和 widget 的数据。例如，您可以验证文本输入字段是否包含用户输入的文本，或者其中包含特定数量的字符。
设置操作所需的微件
作为卡片的 action 的一部分，将操作所需的 widget 名称添加到其 requiredWidgets 列表中。
如果此处列出的任何 widget 在调用此方法时都没有值，则会取消表单操作提交。
为某项操作设置 "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 的验证字段中，它可以指定此文本输入 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 应用或卡片返回错误时，Chat 界面会显示一条消息，提示“出了点问题”。或“无法处理您的请求”。有时，Chat 界面不显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。
虽然 Chat 界面中可能未显示错误消息，但当为 Chat 应用启用错误日志记录时，系统会提供描述性错误消息和日志数据来帮助您修复错误。如需查看、调试和修正错误方面的帮助，请参阅排查和修正 Google Chat 错误。