Cards v2

卡片

在 Google Chat 消息或 Google Workspace 插件中显示的卡片界面。

卡片支持定义的布局、按钮等交互式界面元素，以及图片等富媒体。使用卡片来呈现详细信息、从用户那里收集信息，以及引导用户执行后续步骤。

使用卡片制作工具设计和预览卡片。

打开卡片制作工具

如需了解如何构建卡片，请参阅以下文档：

• 对于 Google Chat 应用，请参阅设计卡片或对话框的组件。
• 对于 Google Workspace 插件，请参阅基于卡片的界面。

注意：每张卡片最多可添加 100 个微件。超出此限制的所有微件都会被忽略。此限制同时适用于 Google Chat 应用中的卡片消息和对话，以及 Google Workspace 插件中的卡片。

示例：Google Chat 应用的卡片消息

如需在 Google Chat 中创建示例卡片消息，请使用以下 JSON：

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
           "title": "Sasha",
           "subtitle": "Software Engineer",
           "imageUrl":
           "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png",
           "imageType": "CIRCLE",
           "imageAltText": "Avatar for Sasha"
         },
         "sections": [
           {
             "header": "Contact Info",
             "collapsible": true,
             "uncollapsibleWidgetsCount": 1,
             "widgets": [
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "EMAIL"
                   },
                   "text": "[e-mail]"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PERSON"
                   },
                   "text": "<font color=\"#80e27e\">Online</font>"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PHONE"
                   },
                   "text": "[phone]"
                 }
               },
               {
                 "buttonList": {
                   "buttons": [
                     {
                       "text": "Share",
                       "onClick": {
                        "openLink": {
                           "url": "https://example.com/share"
                         }
                       }
                     },
                     {
                       "text": "Edit",
                       "onClick": {
                         "action": {
                           "function": "goToView",
                           "parameters": [
                             {
                               "key": "viewType",
                               "value": "EDIT"
                             }
                           ]
                         }
                       }
                     }
                   ]
                 }
               }
             ]
           }
         ]
       }
    }
  ]
}

JSON 表示法
{ "header": { object (CardHeader) }, "sections": [ { object (Section) } ], "sectionDividerStyle": enum (DividerStyle), "cardActions": [ { object (CardAction) } ], "name": string, "fixedFooter": { object (CardFixedFooter) }, "displayStyle": enum (DisplayStyle), "peekCardHeader": { object (CardHeader) } }

字段
header	object (CardHeader) 卡片的标题。标题通常包含一张前置图片和一个标题。标题始终显示在卡片顶部。
sections[]	object (Section) 包含一组 widget。每个部分都有自己的可选标题。各部分之间用线条分隔。如需查看 Google Chat 应用中的示例，请参阅定义卡片的部分。
sectionDividerStyle	enum (DividerStyle) 标题、部分和页脚之间的分隔线样式。
cardActions[]	object (CardAction) 卡片的操作。操作会添加到卡片的工具栏菜单中。 Google Workspace 插件支持此功能，Google Chat 应用不支持。 例如，以下 JSON 使用 Settings 和 Send Feedback 选项构建卡片操作菜单： "cardActions": [ { "actionLabel": "Settings", "onClick": { "action": { "functionName": "goToView", "parameters": [ { "key": "viewType", "value": "SETTING" } ], "loadIndicator": "LoadIndicator.SPINNER" } } }, { "actionLabel": "Send Feedback", "onClick": { "openLink": { "url": "https://example.com/feedback" } } } ]
name	string 卡片的名称。在卡片导航中用作卡片标识符。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
fixedFooter	object (CardFixedFooter) 此卡片底部显示的固定页脚。 如果设置 fixedFooter 而不指定 primaryButton 或 secondaryButton，则会导致错误。对于 Chat 应用，您可以在对话框中使用固定页脚，但不能在卡片消息中使用。 适用于 Google Chat 应用和 Google Workspace 插件。
displayStyle	enum (DisplayStyle) 在 Google Workspace 插件中，设置 peekCardHeader 的显示属性。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
peekCardHeader	object (CardHeader) 在显示情境内容时，预览卡片标题会用作占位符，以便用户在首页卡片和情境卡片之间前进导航。 Google Workspace 插件支持此功能，Google Chat 应用不支持。

CardHeader

表示卡片标题。如需查看 Google Chat 应用中的示例，请参阅添加标题。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "title": string, "subtitle": string, "imageType": enum (ImageType), "imageUrl": string, "imageAltText": string }

字段
title	string 必需。卡片标题的标题。标题的高度是固定的：如果同时指定了标题和副标题，则每个标题占一行。如果仅指定标题，则标题会占据两行。
subtitle	string 卡片标题的副标题。如果已指定，则显示在 title 下方单独的一行中。
imageType	enum (ImageType) 用于剪裁图片的形状。 适用于 Google Chat 应用和 Google Workspace 插件。
imageUrl	string 卡片标题中图片的 HTTPS 网址。
imageAltText	string 此图片的替代文本，用于无障碍功能。

ImageType

用于剪裁图片的形状。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
SQUARE	默认值。向图片应用方形蒙版。例如，4x3 图片会变为 3x3。
CIRCLE	对图片应用圆形蒙版。例如，4x3 图片会变成直径为 3 的圆形。

版块

版块包含一组微件，这些微件会按照指定的顺序垂直呈现。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "header": string, "widgets": [ { object (Widget) } ], "collapsible": boolean, "uncollapsibleWidgetsCount": integer, "collapseControl": { object (CollapseControl) } }

字段
header	string 显示在部分顶部的文字。支持简单的 HTML 格式文本。如需详细了解如何设置文本格式，请参阅在 Google Chat 应用中设置文本格式和在 Google Workspace 插件中设置文本格式。
widgets[]	object (Widget) 该部分中的所有微件。必须包含至少一个 widget。
collapsible	boolean 指示此部分是否可收起。 可收起的部分会隐藏部分或全部微件，但用户可以点击展开来展开该部分，以显示隐藏的微件。用户可以点击显示较少，再次隐藏这些微件。 如需确定要隐藏哪些微件，请指定 uncollapsibleWidgetsCount。
uncollapsibleWidgetsCount	integer 即使某个版块处于收起状态，仍会显示的不可收起微件的数量。 例如，如果某个版块包含 5 个 widget，并且 uncollapsibleWidgetsCount 设置为 2，则前两个 widget 始终会显示，最后三个 widget 默认处于收起状态。只有在 collapsible 为 true 时，系统才会考虑 uncollapsibleWidgetsCount。
collapseControl	object (CollapseControl) 可选。定义该部分的展开和收起按钮。只有当该部分可收起时，系统才会显示此按钮。如果未设置此字段，则使用默认按钮。

Widget

每张卡片都由微件组成。

widget 是一种复合对象，可以表示文本、图片、按钮和其他对象类型之一。

JSON 表示法

{ "horizontalAlignment": enum (HorizontalAlignment), // Union field data can be only one of the following: "textParagraph": { object (TextParagraph) }, "image": { object (Image) }, "decoratedText": { object (DecoratedText) }, "buttonList": { object (ButtonList) }, "textInput": { object (TextInput) }, "selectionInput": { object (SelectionInput) }, "dateTimePicker": { object (DateTimePicker) }, "divider": { object (Divider) }, "grid": { object (Grid) }, "columns": { object (Columns) }, "carousel": { object (Carousel) }, "chipList": { object (ChipList) } // End of list of possible types for union field data. }

字段
horizontalAlignment	enum (HorizontalAlignment) 指定 widget 是沿列的左侧、右侧还是中间对齐。
联合字段 data。一个 widget 只能包含以下各项之一。您可以使用多个 widget 字段来显示更多项。 data只能是以下其中一项：
textParagraph	object (TextParagraph) 显示文本段落。支持简单的 HTML 格式文本。如需详细了解如何设置文本格式，请参阅在 Google Chat 应用中设置文本格式和在 Google Workspace 插件中设置文本格式。 例如，以下 JSON 会创建粗体文本： "textParagraph": { "text": " <b>bold text</b>" }
image	object (Image) 显示图片。 例如，以下 JSON 会创建带替代文本的图片： "image": { "imageUrl": "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png", "altText": "Chat app avatar" }
decoratedText	object (DecoratedText) 显示装饰的文本项。 例如，以下 JSON 会创建一个显示电子邮件地址的装饰文本微件： "decoratedText": { "icon": { "knownIcon": "EMAIL" }, "topLabel": "Email Address", "text": "[e-mail]", "bottomLabel": "This is a new Email address!", "switchControl": { "name": "has_send_welcome_email_to_sasha", "selected": false, "controlType": "CHECKBOX" } }
buttonList	object (ButtonList) 按钮列表。 例如，以下 JSON 会创建两个按钮。第一个是蓝色的文本按钮，第二个是用于打开链接的图片按钮： "buttonList": { "buttons": [ { "text": "Edit", "color": { "red": 0, "green": 0, "blue": 1, }, "disabled": true, }, { "icon": { "knownIcon": "INVITE", "altText": "check calendar" }, "onClick": { "openLink": { "url": "https://example.com/calendar" } } } ] }
textInput	object (TextInput) 显示一个供用户输入文本的文本框。 例如，以下 JSON 会为电子邮件地址创建文本输入： "textInput": { "name": "mailing_address", "label": "Mailing Address" } 再举一个例子，以下 JSON 会为具有静态建议的编程语言创建文本输入： "textInput": { "name": "preferred_programing_language", "label": "Preferred Language", "initialSuggestions": { "items": [ { "text": "C++" }, { "text": "Java" }, { "text": "JavaScript" }, { "text": "Python" } ] } }
selectionInput	object (SelectionInput) 显示一个选择控件，供用户选择内容。选择控件可以是复选框、单选按钮、开关或下拉菜单。 例如，以下 JSON 会创建一个下拉菜单，供用户选择尺寸： "selectionInput": { "name": "size", "label": "Size" "type": "DROPDOWN", "items": [ { "text": "S", "value": "small", "selected": false }, { "text": "M", "value": "medium", "selected": true }, { "text": "L", "value": "large", "selected": false }, { "text": "XL", "value": "extra_large", "selected": false } ] }
dateTimePicker	object (DateTimePicker) 显示一个微件，供用户输入日期、时间或日期和时间。 例如，以下 JSON 会创建一个日期时间选择器来安排预约： "dateTimePicker": { "name": "appointment_time", "label": "Book your appointment at:", "type": "DATE_AND_TIME", "valueMsEpoch": "796435200000" }
divider	object (Divider) 在微件之间显示水平线分隔符。 例如，以下 JSON 会创建一个分隔符： "divider": { }
grid	object (Grid) 显示包含一组项的网格。 网格支持任意数量的列和项。行数由项数上限除以列数决定。一个包含 10 项和 2 列的网格有 5 行。一个包含 11 项和 2 列的网格有 6 行。 适用于 Google Chat 应用和 Google Workspace 插件。 例如，以下 JSON 会创建一个包含单个项的 2 列网格： "grid": { "title": "A fine collection of items", "columnCount": 2, "borderStyle": { "type": "STROKE", "cornerRadius": 4 }, "items": [ { "image": { "imageUri": "https://www.example.com/image.png", "cropStyle": { "type": "SQUARE" }, "borderStyle": { "type": "STROKE" } }, "title": "An item", "textAlignment": "CENTER" } ], "onClick": { "openLink": { "url": "https://www.example.com" } } }
columns	object (Columns) 最多显示 2 列。 如需添加超过 2 列或使用行，请使用 Grid widget。 例如，以下 JSON 会创建 2 个列，每个列都包含文本段落： "columns": { "columnItems": [ { "horizontalSizeStyle": "FILL_AVAILABLE_SPACE", "horizontalAlignment": "CENTER", "verticalAlignment": "CENTER", "widgets": [ { "textParagraph": { "text": "First column text paragraph" } } ] }, { "horizontalSizeStyle": "FILL_AVAILABLE_SPACE", "horizontalAlignment": "CENTER", "verticalAlignment": "CENTER", "widgets": [ { "textParagraph": { "text": "Second column text paragraph" } } ] } ] }
carousel	object (Carousel) 轮播界面包含一系列嵌套的微件。例如，以下是包含两个文本段落的轮播界面的 JSON 表示法。 { "widgets": [ { "textParagraph": { "text": "First text paragraph in the carousel." } }, { "textParagraph": { "text": "Second text paragraph in the carousel." } } ] }
chipList	object (ChipList) 条状标签列表。 例如，以下 JSON 会创建两个条状标签。第一个是文本条状标签，第二个是用于打开链接的图标条状标签： "chipList": { "chips": [ { "text": "Edit", "disabled": true, }, { "icon": { "knownIcon": "INVITE", "altText": "check calendar" }, "onClick": { "openLink": { "url": "https://example.com/calendar" } } } ] }

TextParagraph

支持格式的文本段落。如需查看 Google Chat 应用中的示例，请参阅添加一段格式设置的文本。如需详细了解如何设置文本格式，请参阅在 Google Chat 应用中设置文本格式和在 Google Workspace 插件中设置文本格式。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "text": string, "maxLines": integer }

字段
text	string 在 widget 中显示的文本。
maxLines	integer 在 widget 中显示的文本行数上限。如果文本超过指定的行数上限，则多余的内容会隐藏在展开按钮后面。如果文本等于或短于指定的行数上限，系统不会显示展开按钮。 默认值为 0，在这种情况下，系统会显示所有上下文。系统会忽略负值。

图片

通过网址指定的图片，可以包含 onClick 操作。如需查看示例，请参阅添加图片。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "imageUrl": string, "onClick": { object (OnClick) }, "altText": string }

字段
imageUrl	string 托管图片的 HTTPS 网址。 例如： https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png
onClick	object (OnClick) 当用户点击图片时，点击操作会触发此操作。
altText	string 此图片的替代文本，用于无障碍功能。

OnClick

表示在用户点击卡片上的交互元素（例如按钮）时如何响应。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ // Union field data can be only one of the following: "action": { object (Action) }, "openLink": { object (OpenLink) }, "openDynamicLinkAction": { object (Action) }, "card": { object (Card) }, "overflowMenu": { object (OverflowMenu) } // End of list of possible types for union field data. }

字段
联合字段 data。 data只能是下列其中一项：
action	object (Action) 如果指定，此 onClick 会触发操作。
openLink	object (OpenLink) 如果指定，此 onClick 会触发打开链接操作。
openDynamicLinkAction	object (Action) 当操作需要打开链接时，插件会触发此操作。这与上面的 openLink 不同，因为它需要与服务器通信才能获取链接。因此，在打开链接操作响应返回之前，Web 客户端需要执行一些准备工作。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
card	object (Card) 点击后，系统会将新卡片推送到卡片堆栈（如果指定）。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
overflowMenu	object (OverflowMenu) 如果指定，此 onClick 会打开菜单。

操作

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

适用于 Google Chat 应用和 Google Workspace 插件。

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

字段
function	string 在包含元素被点击或以其他方式激活时调用的自定义函数。 如需查看使用示例，请参阅读取表单数据。
parameters[]	object (ActionParameter) 操作参数列表。
loadIndicator	enum (LoadIndicator) 指定在调用操作时操作显示的加载指示器。
persistValues	boolean 指示表单值在操作后是否保留。默认值为 false。 如果为 true，则表单值会在触发操作后保留。如需允许用户在处理操作期间进行更改，请将 LoadIndicator 设为 NONE。对于 Chat 应用中的卡片消息，您还必须将操作的 ResponseType 设置为 UPDATE_MESSAGE，并使用包含该操作的卡片中的相同 cardId。 如果为 false，则在触发操作时清除表单值。如需在处理操作期间阻止用户进行更改，请将 LoadIndicator 设置为 SPINNER。
interaction	enum (Interaction) 可选。打开对话框时必须提供。 如何响应与用户的互动，例如用户点击卡片消息中的按钮。 如果未指定，应用会像往常一样执行 action（例如打开链接或运行函数）来响应。 通过指定 interaction，应用可以以特殊的互动方式做出响应。例如，通过将 interaction 设置为 OPEN_DIALOG，应用可以打开对话框。指定此属性后，系统不会显示加载指示器。如果为插件指定了此属性，系统会移除整个卡片，客户端中不会显示任何内容。 Google Chat 应用支持此功能，Google Workspace 插件不支持。
requiredWidgets[]	string 可选。在此列表中填写此 Action 需要包含的 widget 的名称，以便有效提交。 如果在调用此 Action 时，此处列出的 widget 没有值，系统会中止表单提交。 适用于 Google Chat 应用和 Google Workspace 插件。
allWidgetsAreRequired	boolean 可选。如果为 true，则系统会将所有 widget 都视为此操作所必需的。 适用于 Google Chat 应用和 Google Workspace 插件。

ActionParameter

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

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

适用于 Google Chat 应用和 Google Workspace 插件。

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

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

LoadIndicator

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

适用于 Google Chat 应用和 Google Workspace 插件。

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

互动

可选。打开对话框时必须提供。

如何响应与用户的互动，例如用户点击卡片消息中的按钮。

如果未指定，应用会像往常一样执行 action（例如打开链接或运行函数）来响应。

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

指定此属性后，系统不会显示加载指示器。如果为插件指定了此属性，系统会移除整个卡片，客户端中不会显示任何内容。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

枚举
INTERACTION_UNSPECIFIED	默认值。action 会照常执行。
OPEN_DIALOG	打开对话框，这是一种基于窗口的卡片式界面，聊天应用会使用它与用户互动。 仅 Chat 应用支持，用于响应卡片消息中的按钮点击。如果为插件指定了此属性，系统会移除整个卡片，客户端中不会显示任何内容。 Google Chat 应用支持此功能，Google Workspace 插件不支持。

OpenLink

表示用于打开超链接的 onClick 事件。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "url": string, "openAs": enum (OpenAs), "onClose": enum (OnClose) }

字段
url	string 要打开的网址。
openAs	enum (OpenAs) 如何打开链接。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
onClose	enum (OnClose) 客户端在打开链接后是否会忘记该链接，还是会一直观察该链接直到窗口关闭。 Google Workspace 插件支持此功能，Google Chat 应用不支持。

OpenAs

当 OnClick 操作打开链接时，客户端可以将其作为全尺寸窗口（如果这是客户端使用的框架）或叠加层（例如弹出式窗口）打开。实现取决于客户端平台功能，如果客户端不支持所选值，系统可能会忽略该值。 所有客户端都支持 FULL_SIZE。

适用于 Google Workspace 插件，不适用于 Google Chat 应用。

枚举
FULL_SIZE	链接会以全尺寸窗口的形式打开（如果客户端使用的是该框架）。
OVERLAY	链接会以叠加层（例如弹出式窗口）的形式打开。

OnClose

当通过 OnClick 操作打开的链接关闭时，客户端执行的操作。

具体实现取决于客户端平台功能。例如，网络浏览器可能会使用 OnClose 处理脚本在弹出式窗口中打开链接。

如果同时设置了 OnOpen 和 OnClose 处理脚本，并且客户端平台无法支持这两个值，则以 OnClose 为准。

适用于 Google Workspace 插件，不适用于 Google Chat 应用。

枚举
NOTHING	默认值。卡片不会重新加载；系统不会执行任何操作。
RELOAD	在子窗口关闭后重新加载卡片。 如果与 OpenAs.OVERLAY 结合使用，子窗口会充当模态对话框，并且父级卡片会被屏蔽，直到子窗口关闭。

OverflowMenu

此 widget 会显示一个包含用户可以调用的一项或多项操作的弹出式菜单。例如，在卡片中显示非主要操作。如果操作不适合放在可用空间中，您可以使用此微件。如需使用，请在支持此 widget 的 widget 的 OnClick 操作中指定此 widget。例如，在 Button 中。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "items": [ { object (OverflowMenuItem) } ] }

字段
items[]	object (OverflowMenuItem) 必需。菜单选项列表。

OverflowMenuItem

用户可以在菜单中调用的选项。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "startIcon": { object (Icon) }, "text": string, "onClick": { object (OnClick) }, "disabled": boolean }

字段
startIcon	object (Icon) 显示在文本前面的图标。
text	string 必需。用于向用户标识或描述项的文本。
onClick	object (OnClick) 必需。选择菜单选项时调用的操作。此 OnClick 不能包含 OverflowMenu，任何指定的 OverflowMenu 都会被丢弃，并且菜单项会被停用。
disabled	boolean 菜单选项是否已停用。默认值为 false。

图标

卡片上 widget 中显示的图标。如需查看 Google Chat 应用中的示例，请参阅添加图标。

支持内置和自定义图标。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "altText": string, "imageType": enum (ImageType), // Union field icons can be only one of the following: "knownIcon": string, "iconUrl": string, "materialIcon": { object (MaterialIcon) } // End of list of possible types for union field icons. }

字段
altText	string 可选。用于无障碍功能的图标的说明。如果未指定，则系统会提供默认值 Button。最佳实践是，您应为图标显示的内容以及其用途（如果适用）设置有用的说明。例如 A user's account portrait 或 Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/workspace/chat。 如果图标是在 Button 中设置的，则当用户将鼠标悬停在按钮上时，altText 会显示为帮助文本。不过，如果按钮还设置了 text，系统会忽略图标的 altText。
imageType	enum (ImageType) 应用于图片的剪裁样式。在某些情况下，应用 CIRCLE 剪裁会导致图片绘制得比内置图标大。
联合字段 icons。卡片上 widget 中显示的图标。 icons只能是以下其中一项：
knownIcon	string 显示 Google Workspace 提供的内置图标之一。 例如，如需显示飞机图标，请指定 AIRPLANE。对于公交车，请指定 BUS。 如需查看支持的图标的完整列表，请参阅内置图标。
iconUrl	string 显示托管在 HTTPS 网址上的自定义图标。 例如： "iconUrl": "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png" 支持的文件类型包括 .png 和 .jpg。
materialIcon	object (MaterialIcon) 显示一个 Google Material 图标。 例如，如需显示复选框图标，请使用以下代码： "materialIcon": { "name": "check_box" } Google Chat 应用支持此功能，Google Workspace 插件不支持。

MaterialIcon

Google Material 图标，包含 2500 多个选项。

例如，如需显示带有自定义权重和等级的复选框图标，请编写以下代码：

{
  "name": "check_box",
  "fill": true,
  "weight": 300,
  "grade": -25
}

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ "name": string, "fill": boolean, "weight": integer, "grade": integer }

字段
name	string Google Material 图标中定义的图标名称，例如 check_box。系统会舍弃所有无效名称并将其替换为空字符串，这会导致图标无法呈现。
fill	boolean 图标是否以填充状态呈现。默认值为 false。 如需预览不同的图标设置，请前往 Google 字体图标，然后调整自定义下的设置。
weight	integer 图标的描边粗细。请从 {100, 200, 300, 400, 500, 600, 700} 中进行选择。如果不存在，默认值为 400。如果指定任何其他值，则使用默认值。 如需预览不同的图标设置，请前往 Google 字体图标，然后调整自定义下的设置。
grade	integer Weight 和 Grade 会影响符号的粗细。调整 Grade 比调整 Weight 更精细，对符号大小的影响较小。请从 {-25, 0, 200} 中进行选择。如果不存在，默认值为 0。如果指定任何其他值，则使用默认值。 如需预览不同的图标设置，请前往 Google 字体图标，然后调整自定义下的设置。

DecoratedText

用于显示文本的 widget，可添加可选装饰，例如文本上方或下方的标签、文本前面的图标、文本后的选择 widget 或按钮。如需查看 Google Chat 应用中的示例，请参阅显示带有装饰文本的文本。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "icon": { object (Icon) }, "startIcon": { object (Icon) }, "topLabel": string, "text": string, "wrapText": boolean, "bottomLabel": string, "onClick": { object (OnClick) }, // Union field control can be only one of the following: "button": { object (Button) }, "switchControl": { object (SwitchControl) }, "endIcon": { object (Icon) } // End of list of possible types for union field control. }

字段
icon (deprecated)	object (Icon) 此项已废弃！ 已废弃，取而代之的是 startIcon。
startIcon	object (Icon) 显示在文本前面的图标。
topLabel	string 显示在 text 上方的文本。始终截断。
text	string 必需。主要文本。 支持简单的格式设置。如需详细了解如何设置文本格式，请参阅在 Google Chat 应用中设置文本格式和在 Google Workspace 插件中设置文本格式。
wrapText	boolean “文字环绕”设置。如果为 true，文本会换行并显示在多行中。否则，系统会截断文本。 仅适用于 text，而不适用于 topLabel 和 bottomLabel。
bottomLabel	string text 下方显示的文字。始终换行。
onClick	object (OnClick) 当用户点击 topLabel 或 bottomLabel 时，系统会触发此操作。
联合字段 control。显示在 decoratedText widget 中文本右侧的按钮、开关、复选框或图片。 control只能是以下其中一项：
button	object (Button) 用户可以点击该按钮来触发操作。
switchControl	object (SwitchControl) 开关 widget，用户可以点击该 widget 来更改其状态并触发操作。
endIcon	object (Icon) 显示在文本后面的图标。 支持内置和自定义图标。

按钮

用户可以点击的文本、图标或文本和图标按钮。如需查看 Google Chat 应用中的示例，请参阅添加按钮。

如需将图片设为可点击的按钮，请指定 Image（而非 ImageComponent）并设置 onClick 操作。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "text": string, "icon": { object (Icon) }, "color": { object (Color) }, "onClick": { object (OnClick) }, "disabled": boolean, "altText": string, "type": enum (Type) }

字段
text	string 按钮内显示的文本。
icon	object (Icon) 按钮内显示的图标。如果同时设置了 icon 和 text，则图标会显示在文本前面。
color	object (Color) 可选。按钮的颜色。如果设置，按钮 type 会设置为 FILLED，text 和 icon 字段的颜色会设置为对比色，以提高可读性。例如，如果将按钮颜色设置为蓝色，则按钮中的所有文本或图标都会设置为白色。 如需设置按钮颜色，请为 red、green 和 blue 字段指定值。该值必须是介于 0 和 1 之间的浮点数，基于 RGB 颜色值，其中 0 (0/255) 表示无颜色，1 (255/255) 表示颜色的最大强度。 例如，以下代码会将颜色设置为红色（强度最高）： "color": { "red": 1, "green": 0, "blue": 0, } alpha 字段不适用于按钮颜色。如果指定，则系统会忽略此字段。
onClick	object (OnClick) 必需。用户点击按钮时要执行的操作，例如打开超链接或运行自定义函数。
disabled	boolean 如果为 true，则按钮显示为非活动状态，并且不会响应用户操作。
altText	string 用于确保可访问性的替代文本。 设置描述性文本，让用户了解该按钮的用途。例如，如果某个按钮会打开超链接，您可以写“打开一个新的浏览器标签页，然后前往 https://developers.google.com/workspace/chat" 查看 Google Chat 开发者文档”。
type	enum (Type) 可选。按钮的类型。如果未设置，按钮类型默认为 OUTLINED。如果设置了 color 字段，系统会强制将按钮类型设为 FILLED，并忽略为此字段设置的任何值。

颜色

表示 RGBA 颜色空间中的一种颜色。此表示法旨在简化各种语言之间的颜色表示法转换，而不是追求紧凑性。例如，此表示法的字段可以轻松提供给 Java 中的 java.awt.Color 构造函数；也可以轻松提供给 iOS 中的 UIColor 的 +colorWithRed:green:blue:alpha 方法；只需稍加处理，便可轻松将其格式化为 JavaScript 中的 CSS rgba() 字符串。

本参考页面不包含应用于解释 RGB 值的绝对颜色空间（例如 sRGB、Adobe RGB、DCI-P3 和 BT.2020）的相关信息。默认情况下，应用应采用 sRGB 颜色空间。

当需要确定颜色是否相等时，除非另有文档说明，否则实现会将两个颜色视为相等，前提是它们的所有红色、绿色、蓝色和 Alpha 值各自的差值不超过 1e-5。

示例 (Java)：

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

示例 (iOS / Obj-C)：

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

示例 (JavaScript)：

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...

JSON 表示法
{ "red": number, "green": number, "blue": number, "alpha": number }

字段
red	number 颜色中的红色量，以介于区间 [0, 1] 内的值表示。
green	number 颜色中的绿色量，以介于区间 [0, 1] 内的值表示。
blue	number 颜色中的蓝色量，以介于区间 [0, 1] 内的值表示。
alpha	number 此颜色在像素中的应用比例。也就是说，最终像素颜色由以下等式定义： pixel color = alpha * (this color) + (1.0 - alpha) * (background color) 也就是说，值为 1.0 表示纯色，而值为 0.0 表示完全透明的颜色。它会使用封装容器消息，而非简单的浮动标量，以便区分默认值和未设置的值。如果省略此字段，此颜色对象将呈现为纯色（就像已明确给定 Alpha 值为 1.0）。

类型

可选。按钮的类型。如果设置了 color 字段，则 type 会被强制设为 FILLED。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

枚举
TYPE_UNSPECIFIED	请勿使用。未指定。
OUTLINED	轮廓按钮是中强调度按钮。其中通常包含重要但不是 Chat 应用或插件中主要操作的操作。
FILLED	填充的按钮具有纯色的容器。这种图标的视觉效果最强，建议用于 Chat 应用或插件中的重要主要操作。
FILLED_TONAL	填充色调按钮介于填充按钮和轮廓按钮之间。在某些情况下，优先级较低的按钮需要比轮廓按钮略显突出，这时就非常适合使用填充按钮。
BORDERLESS	按钮在默认状态下没有不可见的容器。它通常用于优先级最低的操作，尤其是在显示多个选项时。

SwitchControl

decoratedText widget 中的切换开关或复选框。

适用于 Google Chat 应用和 Google Workspace 插件。

仅在 decoratedText 微件中受支持。

JSON 表示法
{ "name": string, "value": string, "selected": boolean, "onChangeAction": { object (Action) }, "controlType": enum (ControlType) }

字段
name	string 在表单输入事件中用于标识开关 widget 的名称。 如需详细了解如何使用表单输入，请参阅接收表单数据。
value	string 用户输入的值，作为表单输入事件的一部分返回。 如需详细了解如何使用表单输入，请参阅接收表单数据。
selected	boolean 为 true 时，开关处于选中状态。
onChangeAction	object (Action) 在开关状态发生变化时要执行的操作，例如要运行的函数。
controlType	enum (ControlType) 开关在界面中的显示方式。 适用于 Google Chat 应用和 Google Workspace 插件。

ControlType

开关在界面中的显示方式。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
SWITCH	切换开关。
CHECKBOX	已废弃，取而代之的是 CHECK_BOX。
CHECK_BOX	复选框。

ButtonList

水平排列的按钮列表。如需查看 Google Chat 应用中的示例，请参阅添加按钮。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "buttons": [ { object (Button) } ] }

字段
buttons[]	object (Button) 按钮数组。

TextInput

供用户输入文本的字段。支持建议和更改时执行的操作。支持表单提交验证。如果 Action.all_widgets_are_required 设置为 true 或在 Action.required_widgets 中指定此微件，则系统会阻止提交操作，除非您输入值。如需查看 Google Chat 应用中的示例，请参阅添加供用户输入文本的字段。

聊天应用会在表单输入事件期间接收并处理输入文本的值。如需详细了解如何使用表单输入，请参阅接收表单数据。

当您需要从用户收集未定义或抽象数据时，请使用文本输入。如需从用户收集已定义或已枚举的数据，请使用 SelectionInput widget。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "name": string, "label": string, "hintText": string, "value": string, "type": enum (Type), "onChangeAction": { object (Action) }, "initialSuggestions": { object (Suggestions) }, "autoCompleteAction": { object (Action) }, "validation": { object (Validation) }, "placeholderText": string }

字段
name	string 在表单输入事件中用于标识文本输入的名称。 如需详细了解如何使用表单输入，请参阅接收表单数据。
label	string 界面中文本输入字段上方显示的文本。 指定有助于用户输入应用所需信息的文字。例如，如果您要询问某人的姓名，但需要知道对方的姓氏，请写 surname，而不是 name。 如果未指定 hintText，则必须使用此属性。否则，可选。
hintText	string 显示在文本输入字段下方的文本，用于提示用户输入特定值，从而帮助用户。此文本始终可见。 如果未指定 label，则必须使用此属性。否则，可选。
value	string 用户输入的值，作为表单输入事件的一部分返回。 如需详细了解如何使用表单输入，请参阅接收表单数据。
type	enum (Type) 文本输入字段在界面中的显示方式。例如，字段是单行还是多行。
onChangeAction	object (Action) 当文本输入字段发生更改时，应执行的操作。例如，用户向字段添加内容或删除文本。 可执行的操作示例包括在 Google Chat 中运行自定义函数或打开对话框。
initialSuggestions	object (Suggestions) 用户可以输入的建议值。当用户点击文本输入字段时，系统会显示这些值。用户输入内容时，系统会动态过滤建议值，以匹配用户输入的内容。 例如，用于编程语言的文本输入字段可能会建议 Java、JavaScript、Python 和 C++。当用户开始输入 Jav 时，建议列表会过滤为仅显示 Java 和 JavaScript。 建议值有助于引导用户输入您的应用可以理解的值。在提及 JavaScript 时，有些用户可能会输入 javascript，而有些用户可能会输入 java script。建议使用 JavaScript 可以规范用户与应用的互动方式。 指定后，TextInput.type 始终为 SINGLE_LINE，即使将其设置为 MULTIPLE_LINE 也是如此。 适用于 Google Chat 应用和 Google Workspace 插件。
autoCompleteAction	object (Action) 可选。指定当文本输入字段向与其互动的用户提供建议时要执行的操作。 如果未指定，建议由 initialSuggestions 设置并由客户端处理。 如果指定，应用会执行此处指定的操作，例如运行自定义函数。 Google Workspace 插件支持此功能，Google Chat 应用不支持。
validation	object (Validation) 指定此文本字段所需的输入格式验证。 适用于 Google Chat 应用和 Google Workspace 插件。
placeholderText	string 文本输入字段为空时显示的文本。使用此文本提示用户输入值。例如 Enter a number from 0 to 100。 Google Chat 应用支持此功能，Google Workspace 插件不支持。

类型

文本输入字段在界面中的显示方式。例如，它是单行输入字段还是多行输入。如果指定了 initialSuggestions，则 type 始终为 SINGLE_LINE，即使将其设置为 MULTIPLE_LINE 也是如此。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
SINGLE_LINE	文本输入字段的高度固定为 1 行。
MULTIPLE_LINE	文本输入字段的高度固定为多行。

RenderActions

一组渲染指令，用于指示卡片执行操作，或指示插件托管应用或 Chat 应用执行特定于应用的操作。

适用于 Google Chat 应用和 Google Workspace 插件。

字段
action	Action

操作

字段
navigations[]	Navigation 推送、弹出或更新卡片。 开发者预览版：Google Chat 中的插件。

导航

向堆叠添加新卡片（向前导航）。对于 Chat 应用，仅适用于应用首页。

适用于 Google Chat 应用和 Google Workspace 插件。

navigations: {
  pushCard: CARD
}

将顶部卡片替换为新卡片。对于 Chat 应用，仅适用于应用首页。

适用于 Google Chat 应用和 Google Workspace 插件。

navigations: {
  updateCard: CARD
}

字段
联合字段 navigate_action。 navigate_action 只能是下列其中一项：
pushCard	Card 将卡片推送到卡片堆栈。 开发者预览版：对于 Google Chat 中的对话框，用于打开或更新对话框。
updateCard	Card 使用新卡片更新顶部卡片，并保留已填充的表单字段值。对于不等效的字段，系统会舍弃该值。 开发者预览版：对于 Google Chat 中的对话框，用于打开或更新对话框。

建议

用户可以输入的建议值。当用户点击文本输入字段时，系统会显示这些值。用户输入内容时，系统会动态过滤建议值，以匹配用户输入的内容。

例如，用于编程语言的文本输入字段可能会建议 Java、JavaScript、Python 和 C++。当用户开始输入 Jav 时，建议列表会过滤为显示 Java 和 JavaScript。

建议值有助于引导用户输入您的应用可以理解的值。在提及 JavaScript 时，有些用户可能会输入 javascript，而有些用户可能会输入 java script。建议使用 JavaScript 可以规范用户与应用的互动方式。

指定后，TextInput.type 始终为 SINGLE_LINE，即使将其设置为 MULTIPLE_LINE 也是如此。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "items": [ { object (SuggestionItem) } ] }

字段
items[]	object (SuggestionItem) 用于在文本输入字段中提供自动补全建议的建议列表。

SuggestionItem

用户可以在文本输入字段中输入的一个建议值。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ // Union field content can be only one of the following: "text": string // End of list of possible types for union field content. }

字段
联合字段 content。 content只能是下列其中一项：
text	string 文本输入字段的建议输入值。这相当于用户自行输入的内容。

验证

表示验证其所附加的 widget 所需的数据。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "characterLimit": integer, "inputType": enum (InputType) }

字段
characterLimit	integer 指定文本输入 widget 的字符数限制。请注意，此属性仅用于文本输入，系统会忽略其他 widget 的此属性。 适用于 Google Chat 应用和 Google Workspace 插件。
inputType	enum (InputType) 指定输入 widget 的类型。 适用于 Google Chat 应用和 Google Workspace 插件。

InputType

输入 widget 的类型。

枚举
INPUT_TYPE_UNSPECIFIED	未指定类型。请勿使用。
TEXT	接受所有字符的常规文本。
INTEGER	整数值。
FLOAT	浮点值。
EMAIL	电子邮件地址。
EMOJI_PICKER	从系统提供的表情符号选择器中选择的表情符号。

SelectionInput

用于创建用户可选择的一个或多个界面项的 widget。仅支持对 dropdown 和 multiselect 菜单进行表单提交验证。如果 Action.all_widgets_are_required 设置为 true 或在 Action.required_widgets 中指定了此微件，则除非选择某个值，否则系统会阻止提交操作。例如，下拉菜单或复选框。您可以使用此微件收集可预测或枚举的数据。如需查看 Google Chat 应用中的示例，请参阅添加可选择的界面元素。

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

如需从用户收集未定义或抽象数据，请使用 TextInput widget。

适用于 Google Chat 应用和 Google Workspace 插件。

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) 在 SelectionInput widget 中向用户显示的项的类型。选择类型支持不同类型的互动。例如，用户可以选择一个或多个复选框，但只能从下拉菜单中选择一个值。
items[]	object (SelectionItem) 可选项的数组。例如，单选按钮或复选框的数组。最多支持 100 项内容。
onChangeAction	object (Action) 如果已指定，则在选择发生变化时提交表单。如果未指定，则必须指定单独用于提交表单的按钮。 如需详细了解如何使用表单输入，请参阅接收表单数据。
multiSelectMaxSelectedItems	integer 对于多选菜单，表示用户可选择的项数上限。最小值为 1 件。如果未指定，则默认为 3 项。
multiSelectMinQueryLength	integer 对于多选菜单，是用户在菜单返回建议的选择项之前输入的文本字符数。 如果未设置，多选菜单将使用以下默认值： 如果菜单使用 SelectionInput 项的静态数组，则默认为 0 个字符，并立即从数组中填充项。 如果菜单使用动态数据源 (multi_select_data_source)，则默认为 3 个字符，在查询数据源以返回建议项之前。
联合字段 multi_select_data_source。对于多选菜单，是一个用于动态填充选择项的数据源。 Google Chat 应用支持此功能，Google Workspace 插件不支持。 multi_select_data_source只能是下列其中一项：
externalDataSource	object (Action) 外部数据源，例如关系型数据库。
platformDataSource	object (PlatformDataSource) Google Workspace 中的数据源。

SelectionType

用户可选择的项的格式。不同的选项支持不同的互动类型。例如，用户可以选择多个复选框，但只能从下拉菜单中选择一项。

每个选择输入都支持一种选择类型。例如，不支持混合使用复选框和开关。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
CHECK_BOX	一组复选框。用户可以选中一个或多个复选框。
RADIO_BUTTON	一组单选按钮。用户可以选择一个单选按钮。
SWITCH	一组开关。用户可以开启一个或多个开关。
DROPDOWN	下拉菜单。用户可以从菜单中选择一个项目。
MULTI_SELECT	包含文本框的菜单。用户可以输入内容并选择一个或多个项。对于 Google Workspace 插件，您必须使用 SelectionItem 对象的静态数组填充项。 对于 Google Chat 应用，您还可以使用动态数据源填充项，并在用户在菜单中输入内容时自动建议项。例如，用户可以开始输入 Google Chat 聊天室的名称，然后该 widget 会自动建议该聊天室。如需为多选菜单动态填充项，请使用以下某种类型的数据源： Google Workspace 数据：系统会使用 Google Workspace 中的数据（例如 Google Workspace 用户或 Google Chat 聊天室）填充内容。 外部数据：项目是从 Google Workspace 之外的外部数据源填充的。 如需查看如何为 Chat 应用实现多选菜单的示例，请参阅添加多选菜单。 适用于 Google Chat 应用和 Google Workspace 插件。

SelectionItem

用户可以在选择输入中选择的项，例如复选框或开关。最多支持 100 项内容。

适用于 Google Chat 应用和 Google Workspace 插件。

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/workspace/chat/images/quickstart-app-avatar.png。
bottomText	string 对于多选菜单，是显示在项的 text 字段下方的文本说明或标签。

PlatformDataSource

对于使用多选菜单的 SelectionInput widget，请使用 Google Workspace 中的数据源。用于填充多选菜单中的项。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ // Union field data_source can be only one of the following: "commonDataSource": enum (CommonDataSource), "hostAppDataSource": { object (HostAppDataSourceMarkup) } // End of list of possible types for union field data_source. }

字段
联合字段 data_source。数据源。 data_source只能是以下其中一项：
commonDataSource	enum (CommonDataSource) 所有 Google Workspace 应用共享的数据源，例如 Google Workspace 组织中的用户。
hostAppDataSource	object (HostAppDataSourceMarkup) 仅适用于 Google Workspace 托管应用（例如 Google Chat 中的聊天室）的数据源。 此字段支持 Google API 客户端库，但不适用于 Cloud 客户端库。如需了解详情，请参阅安装客户端库。

CommonDataSource

所有 Google Workspace 应用共享的数据源。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

枚举
UNKNOWN	默认值。请勿使用。
USER	Google Workspace 用户。用户只能查看和选择其 Google Workspace 组织中的用户。

HostAppDataSourceMarkup

对于使用多选菜单的 SelectionInput 微件，请使用 Google Workspace 应用中的数据源。数据源会为多选菜单填充选择项。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ // Union field data_source can be only one of the following: "chatDataSource": { object (ChatClientDataSourceMarkup) } // End of list of possible types for union field data_source. }

字段
联合字段 data_source。用于为多选菜单填充项的 Google Workspace 应用。 data_source只能是以下其中一项：
chatDataSource	object (ChatClientDataSourceMarkup) Google Chat 中的数据源。

ChatClientDataSourceMarkup

对于使用多选菜单的 SelectionInput 微件，请使用 Google Chat 中的数据源。数据源会为多选菜单填充选择项。例如，用户可以选择自己是成员的 Google Chat 聊天室。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ // Union field source can be only one of the following: "spaceDataSource": { object (SpaceDataSource) } // End of list of possible types for union field source. }

字段
联合字段 source。Google Chat 数据源。 source只能是以下其中一项：
spaceDataSource	object (SpaceDataSource) 用户所属的 Google Chat 聊天室。

SpaceDataSource

一种数据源，用于将 Google Chat 聊天室填充为多选菜单的选择项。仅填充用户是成员的聊天室。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ "defaultToCurrentSpace": boolean }

字段
defaultToCurrentSpace	boolean 如果设置为 true，多选菜单会默认选择当前 Google Chat 聊天室作为项。

DateTimePicker

让用户输入日期、时间或日期和时间。支持表单提交验证。当 Action.all_widgets_are_required 设置为 true 或在 Action.required_widgets 中指定此微件时，除非选择某个值，否则系统会阻止提交操作。如需查看 Google Chat 应用中的示例，请参阅让用户选择日期和时间。

用户可以输入文本，也可以使用选择器选择日期和时间。如果用户输入的日期或时间无效，选择器会显示错误消息，提示用户正确输入信息。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "name": string, "label": string, "type": enum (DateTimePickerType), "valueMsEpoch": string, "timezoneOffsetDate": integer, "onChangeAction": { object (Action) } }

字段
name	string 在表单输入事件中用于标识 DateTimePicker 的名称。 如需详细了解如何使用表单输入，请参阅接收表单数据。
label	string 提示用户输入日期、时间或日期和时间的文本。例如，如果用户要安排预约，请使用 Appointment date 或 Appointment date and time 等标签。
type	enum (DateTimePickerType) 微件是否支持输入日期、时间或日期和时间。
valueMsEpoch	string (int64 format) 微件中显示的默认值，以自 Unix 纪年时间开始计算的毫秒数表示。 根据选择器的类型 (DateTimePickerType) 指定值： DATE_AND_TIME ：世界协调时间 (UTC) 格式的日历日期和时间。例如，如需表示 2023 年 1 月 1 日世界协调时间 (UTC) 中午 12:00，请使用 1672574400000。 DATE_ONLY ：世界协调时间 (UTC) 00:00:00 的日历日期。例如，如需表示 2023 年 1 月 1 日，请使用 1672531200000。 TIME_ONLY ：世界协调时间 (UTC) 时间。例如，如需表示下午 12:00，请使用 43200000（或 12 * 60 * 60 * 1000）。
timezoneOffsetDate	integer 一个数字，表示相对于世界协调时间 (UTC) 的时区偏移量（以分钟为单位）。如果设置，valueMsEpoch 将显示在指定的时区。如果未设置，则值默认为用户的时区设置。
onChangeAction	object (Action) 当用户点击 DateTimePicker 界面中的保存或清除时触发。

DateTimePickerType

DateTimePicker widget 中日期和时间的格式。确定用户能否输入日期、时间或同时输入日期和时间。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
DATE_AND_TIME	用户输入日期和时间。
DATE_ONLY	用户输入日期。
TIME_ONLY	用户输入时间。

分隔线

此类型没有字段。

以水平线的形式在 widget 之间显示分隔线。如需查看 Google Chat 应用中的示例，请参阅在微件之间添加水平分隔线。

适用于 Google Chat 应用和 Google Workspace 插件。

例如，以下 JSON 会创建一个分隔符：

"divider": {}

网格

显示包含一系列项的网格。项只能包含文字或图片。对于自适应列，或者要添加文本或图片以外的内容，请使用 Columns。如需查看 Google Chat 应用中的示例，请参阅显示包含一系列项的网格。

网格支持任意数量的列和项。行数取决于项数除以列数。一个包含 10 项和 2 列的网格有 5 行。一个包含 11 项和 2 列的网格有 6 行。

适用于 Google Chat 应用和 Google Workspace 插件。

例如，以下 JSON 会创建一个包含单个项的 2 列网格：

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}

JSON 表示法
{ "title": string, "items": [ { object (GridItem) } ], "borderStyle": { object (BorderStyle) }, "columnCount": integer, "onClick": { object (OnClick) } }

字段
title	string 网格标题中显示的文本。
items[]	object (GridItem) 要在网格中显示的项。
borderStyle	object (BorderStyle) 要应用于每个网格项的边框样式。
columnCount	integer 网格中要显示的列数。如果未指定此字段，系统会使用默认值，并且该默认值因显示网格的显示位置（对话框与配套应用）而异。
onClick	object (OnClick) 此回调会由每个网格项重复使用，但会将项的标识符和项列表中的索引添加到回调的参数中。

GridItem

表示网格布局中的项。项可以包含文本、图片，也可以同时包含文本和图片。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "id": string, "image": { object (ImageComponent) }, "title": string, "subtitle": string, "layout": enum (GridItemLayout) }

字段
id	string 此网格项的用户指定标识符。此标识符会在父级网格的 onClick 回调参数中返回。
image	object (ImageComponent) 网格项中显示的图片。
title	string 网格项的标题。
subtitle	string 网格项的副标题。
layout	enum (GridItemLayout) 要为网格项使用的布局。

ImageComponent

表示图片。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "imageUri": string, "altText": string, "cropStyle": { object (ImageCropStyle) }, "borderStyle": { object (BorderStyle) } }

字段
imageUri	string 图片的网址。
altText	string 图片的无障碍功能标签。
cropStyle	object (ImageCropStyle) 要应用于图片的剪裁样式。
borderStyle	object (BorderStyle) 要应用于图片的边框样式。

ImageCropStyle

表示应用于图片的剪裁样式。

适用于 Google Chat 应用和 Google Workspace 插件。

例如，下面展示了如何应用 16:9 宽高比：

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}

JSON 表示法
{ "type": enum (ImageCropType), "aspectRatio": number }

字段
type	enum (ImageCropType) 剪裁类型。
aspectRatio	number 如果剪裁类型为 RECTANGLE_CUSTOM，则要使用的宽高比。 例如，下面展示了如何应用 16:9 宽高比： cropStyle { "type": "RECTANGLE_CUSTOM", "aspectRatio": 16/9 }

ImageCropType

表示应用于图片的剪裁样式。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
IMAGE_CROP_TYPE_UNSPECIFIED	请勿使用。未指定。
SQUARE	默认值。应用方形剪裁。
CIRCLE	应用圆形剪裁。
RECTANGLE_CUSTOM	应用采用自定义宽高比的矩形剪裁。使用 aspectRatio 设置自定义宽高比。
RECTANGLE_4_3	应用宽高比为 4:3 的矩形剪裁。

BorderStyle

卡片或 widget 边框的样式选项，包括边框类型和颜色。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "type": enum (BorderType), "strokeColor": { object (Color) }, "cornerRadius": integer }

字段
type	enum (BorderType) 边框类型。
strokeColor	object (Color) 类型为 BORDER_TYPE_STROKE 时要使用的颜色。 如需设置描边颜色，请为 red、green 和 blue 字段指定值。该值必须是介于 0 和 1 之间的浮点数，基于 RGB 颜色值，其中 0 (0/255) 表示无颜色，1 (255/255) 表示颜色的最大强度。 例如，以下代码会将颜色设置为红色（强度最高）： "color": { "red": 1, "green": 0, "blue": 0, } alpha 字段不适用于描边颜色。如果指定，则系统会忽略此字段。
cornerRadius	integer 边框的圆角半径。

BorderType

表示应用于微件的边框类型。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
BORDER_TYPE_UNSPECIFIED	请勿使用。未指定。
NO_BORDER	默认值。无边框。
STROKE	大纲。

GridItemLayout

表示网格项可用的各种布局选项。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
GRID_ITEM_LAYOUT_UNSPECIFIED	请勿使用。未指定。
TEXT_BELOW	标题和副标题显示在网格项图片下方。
TEXT_ABOVE	标题和副标题会显示在网格项图片上方。

列

Columns widget 在卡片或对话框中最多可显示 2 列。您可以向每列添加微件；微件会按指定的顺序显示。如需查看 Google Chat 应用中的示例，请参阅在列中显示卡片和对话框。

每列的高度由较高列决定。例如，如果第一列比第二列高，则这两列的高度都与第一列相同。由于每列可以包含不同数量的 widget，因此您无法定义行或在列之间对齐 widget。

列会并排显示。您可以使用 HorizontalSizeStyle 字段自定义各列的宽度。如果用户的屏幕宽度过窄，第二列会换行显示在第一列下方：

• 在网站上，如果屏幕宽度小于或等于 480 像素，则第二列会换行。
• 在 iOS 设备上，如果屏幕宽度小于或等于 300 pt，则第二列会换行。
• 在 Android 设备上，如果屏幕宽度小于或等于 320 dp，则第二列会换行。

如需添加多于两列的列或使用行，请使用 Grid widget。

适用于 Google Chat 应用和 Google Workspace 插件。支持列的插件界面包括：

• 当用户从电子邮件草稿打开插件时显示的对话框。
• 当用户从 Google 日历活动的添加附件菜单中打开插件时，系统会显示的对话框。

JSON 表示法
{ "columnItems": [ { object (Column) } ] }

字段
columnItems[]	object (Column) 列数组。您最多可以在卡片或对话框中添加 2 列。

列

列。

Google Workspace 插件和 Chat 应用

JSON 表示法
{ "horizontalSizeStyle": enum (HorizontalSizeStyle), "horizontalAlignment": enum (HorizontalAlignment), "verticalAlignment": enum (VerticalAlignment), "widgets": [ { object (Widgets) } ] }

字段
horizontalSizeStyle	enum (HorizontalSizeStyle) 指定列如何填充卡片的宽度。
horizontalAlignment	enum (HorizontalAlignment) 指定 widget 是沿列的左侧、右侧还是中间对齐。
verticalAlignment	enum (VerticalAlignment) 指定 widget 是与列的顶部、底部还是中心对齐。
widgets[]	object (Widgets) 列中包含的微件数组。微件会按照指定的顺序显示。

HorizontalSizeStyle

指定列如何填充卡片的宽度。每列的宽度取决于 HorizontalSizeStyle 和列中 widget 的宽度。

Google Workspace 插件和 Chat 应用

枚举
HORIZONTAL_SIZE_STYLE_UNSPECIFIED	请勿使用。未指定。
FILL_AVAILABLE_SPACE	默认值。列会填满可用空间，占用空间不超过卡片宽度的 70%。如果将这两个列都设置为 FILL_AVAILABLE_SPACE，则每个列会占据 50% 的空间。
FILL_MINIMUM_SPACE	列占用的空间尽可能少，且不超过卡片宽度的 30%。

HorizontalAlignment

指定 widget 是沿列的左侧、右侧还是中间对齐。

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

枚举
HORIZONTAL_ALIGNMENT_UNSPECIFIED	请勿使用。未指定。
START	默认值。将 widget 对齐到列的起始位置。对于从左到右的布局，请对齐到左侧。对于从右到左的布局，请对齐到右侧。
CENTER	将微件对齐到列的中心。
END	将 widget 对齐到列的末尾位置。对于从左到右的布局，将微件对齐到右侧。对于从右到左的布局，将微件对齐到左侧。

VerticalAlignment

指定 widget 是与列的顶部、底部还是中心对齐。

Google Workspace 插件和 Chat 应用

枚举
VERTICAL_ALIGNMENT_UNSPECIFIED	请勿使用。未指定。
CENTER	默认值。将微件对齐到列的中心。
TOP	将 widget 对齐到列顶部。
BOTTOM	将 widget 对齐到列底部。

微件

您可以在列中添加的受支持微件。

Google Workspace 插件和 Chat 应用

JSON 表示法

{ // Union field data can be only one of the following: "textParagraph": { object (TextParagraph) }, "image": { object (Image) }, "decoratedText": { object (DecoratedText) }, "buttonList": { object (ButtonList) }, "textInput": { object (TextInput) }, "selectionInput": { object (SelectionInput) }, "dateTimePicker": { object (DateTimePicker) }, "chipList": { object (ChipList) } // End of list of possible types for union field data. }

字段
联合字段 data。 data只能是下列其中一项：
textParagraph	object (TextParagraph) TextParagraph 微件。
image	object (Image) Image 微件。
decoratedText	object (DecoratedText) DecoratedText 微件。
buttonList	object (ButtonList) ButtonList 微件。
textInput	object (TextInput) TextInput 微件。
selectionInput	object (SelectionInput) SelectionInput 微件。
dateTimePicker	object (DateTimePicker) DateTimePicker 微件。
chipList	object (ChipList) ChipList 微件。

ChipList

水平排列的条状标签列表，可水平滚动或换行。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "layout": enum (Layout), "chips": [ { object (Chip) } ] }

字段
layout	enum (Layout) 指定的条状标签列表布局。
chips[]	object (Chip) 条状标签数组。

布局

条状标签列表布局。

枚举
LAYOUT_UNSPECIFIED	请勿使用。未指定。
WRAPPED	默认值。如果横向空间不足，条状标签列表会换行到下一行。
HORIZONTAL_SCROLLABLE	如果条状标签无法放入可用空间，则会水平滚动。

Chip

用户可以点击的文本、图标或文本和图标条状标签。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "icon": { object (Icon) }, "label": string, "onClick": { object (OnClick) }, "enabled": boolean, "disabled": boolean, "altText": string }

字段
icon	object (Icon) 图标图片。如果同时设置了 icon 和 text，则图标会显示在文本前面。
label	string 条状标签中显示的文本。
onClick	object (OnClick) 可选。用户点击条状标签时要执行的操作，例如打开超链接或运行自定义函数。
enabled (deprecated)	boolean 此项已废弃！ 条状标签是否处于活动状态并响应用户操作。默认值为 true。已弃用。请改用 disabled。
disabled	boolean 条状标签是否处于非活动状态并忽略用户操作。默认值为 false。
altText	string 用于确保可访问性的替代文本。 设置描述性文本，让用户知道条状标签的用途。例如，如果条状标签会打开超链接，请写“打开一个新的浏览器标签页，然后前往 https://developers.google.com/workspace/chat" 查看 Google Chat 开发者文档”。

轮播界面

开发者预览版：Google Workspace 开发者预览版计划的一部分，可让您抢先体验某些功能。

轮播界面（也称为滑块）会旋转并以幻灯片格式显示微件列表，并提供用于导航到上一个或下一个微件的按钮。

例如，下面是包含三个文本段落微件的轮播界面的 JSON 表示法。

{
  "carouselCards": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "First text paragraph in carousel",
          }
        }
      ]
    },
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "Second text paragraph in carousel",
          }
        }
      ]
    },
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "Third text paragraph in carousel",
          }
        }
      ]
    }
  ]
}

适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ "carouselCards": [ { object (CarouselCard) } ] }

字段
carouselCards[]	object (CarouselCard) 轮播界面中包含的卡片列表。

CarouselCard

开发者预览版：Google Workspace 开发者预览版计划的一部分，可让您抢先体验某些功能。

可作为轮播界面项显示的卡片。 适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ "widgets": [ { object (NestedWidget) } ], "footerWidgets": [ { object (NestedWidget) } ] }

字段
widgets[]	object (NestedWidget) 轮播卡片中显示的微件列表。这些微件会按照指定的顺序显示。
footerWidgets[]	object (NestedWidget) 轮播卡片底部显示的微件列表。这些微件会按照指定的顺序显示。

NestedWidget

开发者预览版：Google Workspace 开发者预览版计划的一部分，可让您抢先体验某些功能。

可在包含布局（例如 CarouselCard）中显示的微件列表。 适用于 Google Chat 应用，不适用于 Google Workspace 插件。

JSON 表示法
{ // Union field data can be only one of the following: "textParagraph": { object (TextParagraph) }, "buttonList": { object (ButtonList) }, "image": { object (Image) } // End of list of possible types for union field data. }

字段
联合字段 data。 data只能是下列其中一项：
textParagraph	object (TextParagraph) 文本段落微件。
buttonList	object (ButtonList) 一个按钮列表 widget。
image	object (Image) 图片微件。

CollapseControl

表示展开和收起控件。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "horizontalAlignment": enum (HorizontalAlignment), "expandButton": { object (Button) }, "collapseButton": { object (Button) } }

字段
horizontalAlignment	enum (HorizontalAlignment) 展开和收起按钮的水平对齐方式。
expandButton	object (Button) 可选。定义一个可自定义的按钮以展开该部分。必须设置 expandButton 和 collapseButton 字段。只有一个字段集不会生效。如果未设置此字段，则使用默认按钮。
collapseButton	object (Button) 可选。定义一个可自定义的按钮来收起该部分。必须设置 expandButton 和 collapseButton 字段。只有一个字段集不会生效。如果未设置此字段，则使用默认按钮。

DividerStyle

卡片的分隔线样式。目前仅用于卡片部分之间的分隔线。

适用于 Google Chat 应用和 Google Workspace 插件。

枚举
DIVIDER_STYLE_UNSPECIFIED	请勿使用。未指定。
SOLID_DIVIDER	默认选项。渲染实心分隔线。
NO_DIVIDER	如果设置，则不会呈现分隔线。此样式会从布局中完全移除分隔线。结果等同于根本不添加分隔符。

CardAction

卡片操作是指与卡片关联的操作。例如，账单卡片可能包含删除账单、通过电子邮件发送账单或在浏览器中打开账单等操作。

适用于 Google Workspace 插件，不适用于 Google Chat 应用。

JSON 表示法
{ "actionLabel": string, "onClick": { object (OnClick) } }

字段
actionLabel	string 显示为操作菜单项的标签。
onClick	object (OnClick) 此操作项的 onClick 操作。

CardFixedFooter

显示在卡片底部的永久性（固定）页脚。

在不指定 primaryButton 或 secondaryButton 的情况下设置 fixedFooter 会导致错误。

对于 Chat 应用，您可以在对话框中使用固定页脚，但不能在卡片消息中使用。如需查看 Google Chat 应用中的示例，请参阅添加永久性页脚。

适用于 Google Chat 应用和 Google Workspace 插件。

JSON 表示法
{ "primaryButton": { object (Button) }, "secondaryButton": { object (Button) } }

字段
primaryButton	object (Button) 固定页脚的主要按钮。该按钮必须是设置了文本和颜色的文本按钮。
secondaryButton	object (Button) 固定页脚的辅助按钮。该按钮必须是设置了文本和颜色的文本按钮。如果设置了 secondaryButton，则还必须设置 primaryButton。

DisplayStyle

在 Google Workspace 插件中，用于确定卡片的显示方式。

适用于 Google Workspace 插件，不适用于 Google Chat 应用。

枚举
DISPLAY_STYLE_UNSPECIFIED	请勿使用。未指定。
PEEK	卡片的标题会显示在侧边栏底部，部分覆盖堆叠的当前顶部卡片。点击标题即可将卡片弹出到卡片堆叠中。如果卡片没有标题，则系统会改用生成的标题。
REPLACE	默认值。系统会通过替换卡片堆叠中顶部卡片的视图来显示该卡片。