Cards v2

卡片

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/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": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "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)

包含一组微件。每个部分都有自己的可选标题。各个部分之间用线条分隔线直观地分隔。如需查看 Google Chat 应用中的示例,请参阅卡片部分

sectionDividerStyle

enum (DividerStyle)

部分之间的分隔线样式。

cardActions[]

object (CardAction)

卡片的操作。操作会添加到卡片的工具栏菜单中。

由于聊天应用卡片没有工具栏,因此 Chat 应用不支持 cardActions[]

例如,以下 JSON 使用 SettingsSend 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

卡片的名称。用作卡片导航中的卡片标识符。

由于聊天应用不支持卡片导航,因此它们会忽略此字段。

displayStyle

enum (DisplayStyle)

在 Google Workspace 插件中,设置 peekCardHeader 的显示属性。

Chat 应用不支持。

peekCardHeader

object (CardHeader)

显示上下文内容时,提示卡标题可充当占位符,以便用户在首页卡片和上下文卡片之间向前导航。

Chat 应用不支持。

CardHeader

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

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

string

必需。卡片标题的标题。标题具有固定的高度:如果同时指定了标题和副标题,则标题会各占一行。如果仅指定标题,则会占用两行。

subtitle

string

卡片标题的副标题。如果指定,则该属性会显示在 title 下方的单独行中。

imageType

enum (ImageType)

用于剪裁图片的形状。

imageUrl

string

卡片标头中图片的 HTTPS 网址。

imageAltText

string

此图片的替代文字,用于提供无障碍功能。

ImageType

用于剪裁图片的形状。

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

章节

版块包含一系列会按照指定顺序垂直呈现的 widget。

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

string

显示在版块顶部的文字。支持简单的 HTML 格式的文本。如需详细了解如何设置文本格式,请参阅设置 Google Chat 应用中的文本格式设置 Google Workspace 插件中的文本格式

widgets[]

object (Widget)

版块中的所有微件。必须包含至少一个微件。

collapsible

boolean

指明此部分是否可收起。

可收起的部分会隐藏部分或所有 widget,但用户可以通过点击 Show more 来展开该部分以显示隐藏的 widget。用户可以通过点击收起再次隐藏这些微件。

如需确定哪些 widget 处于隐藏状态,请指定 uncollapsibleWidgetsCount

uncollapsibleWidgetsCount

integer

即使某个部分处于收起状态也仍然可见的不可折叠 widget 的数量。

例如,如果某个部分包含五个 widget 并且 uncollapsibleWidgetsCount 设置为 2,则默认情况下,前两个 widget 会始终显示,后三个 widget 会默认处于收起状态。仅当 collapsibletrue 时,才会考虑 uncollapsibleWidgetsCount

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)
  }
  // End of list of possible types for union field data.
}
字段
horizontalAlignment

enum (HorizontalAlignment)

指定 widget 是按列的左侧、右侧还是中心对齐。

联合字段 data。微件只能具有以下项之一。您可以使用多个 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/chat/images/quickstart-app-avatar.png",
  "altText": "Chat app avatar"
}
decoratedText

object (DecoratedText)

显示经过装饰的文本项。

例如,以下 JSON 创建了一个显示电子邮件地址的修饰文本 widget:

"decoratedText": {
  "icon": {
    "knownIcon": "EMAIL"
  },
  "topLabel": "Email Address",
  "text": "sasha@example.com",
  "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,
        "alpha": 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)

在 widget 之间显示水平线分隔线。

例如,以下 JSON 会创建一个分隔线:

"divider": {
}
grid

object (Grid)

显示包含一系列项的网格。

网格支持任意数量的列和项。行数由项目数的上限除以列数确定。一个包含 10 个项和 2 列的网格包含 5 行。一个包含 11 个项和 2 列的网格有 6 行。

例如,以下 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"
          }
        }
      ]
    }
  ]
}

TextParagraph

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

JSON 表示法
{
  "text": string
}
字段
text

string

显示在 widget 中的文本。

图片

通过网址指定且可具有 onClick 操作的图片。如需查看示例,请参阅映像

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

string

托管映像的 HTTPS 网址。

例如:

https://developers.google.com/chat/images/quickstart-app-avatar.png
onClick

object (OnClick)

当用户点击图片时,点击会触发此操作。

altText

string

此图片的替代文字,用于提供无障碍功能。

OnClick

表示在用户点击卡片上的互动元素(例如按钮)时如何响应。

JSON 表示法
{

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

联合字段 data

data 只能是下列其中一项:

action

object (Action)

如果已指定,此 onClick 将触发操作。

card

object (Card)

用户点击广告后,系统会将其推送到卡片堆栈(如果已指定)。

受 Google Workspace 插件支持,但不支持 Google Chat 应用。

操作

描述提交表单时行为的操作。例如,您可以调用 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

参数的值。

LoadIndicator

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

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

互动

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

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

如果未指定,应用将通过正常方式执行 action(例如打开链接或运行函数)进行响应。

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

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

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

枚举
INTERACTION_UNSPECIFIED 默认值。action 照常执行。
OPEN_DIALOG

打开一个对话框,这是一个基于窗口的卡片界面,供 Chat 应用用于与用户互动。

只有聊天应用支持响应卡片消息上的按钮点击操作。

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

OpenAs

OnClick 操作打开链接时,客户端可以将其打开为完整尺寸的窗口(如果这是客户端使用的框架),或者以叠加层(例如弹出式窗口)的形式打开。具体实现取决于客户端平台的功能;如果客户端不支持,所选值可能会被忽略。 所有客户端均支持 FULL_SIZE

受 Google Workspace 插件支持,但不支持 Google Chat 应用。

枚举
FULL_SIZE 链接会以完整尺寸的窗口打开(如果客户端使用的框架就是该框架)。
OVERLAY 链接会作为叠加层(例如弹出式窗口)打开。

OnClose

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

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

如果同时设置了 OnOpenOnClose 处理程序,且客户端平台无法同时支持这两个值,则以 OnClose 为准。

受 Google Workspace 插件支持,但不支持 Google Chat 应用。

枚举
NOTHING 默认值。卡片不会重新加载;没有任何反应。
RELOAD

在子窗口关闭后重新加载卡片。

如果与 OpenAs.OVERLAY 结合使用,子窗口将充当模态对话框,父卡片会被屏蔽,直到子窗口关闭。

装饰文本

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

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,而不适用于 topLabelbottomLabel

bottomLabel

string

text 下方显示的文本。始终封装。

onClick

object (OnClick)

当用户点击 topLabelbottomLabel 时,就会触发此操作。

联合字段 control。显示在 decoratedText widget 中文本右侧的按钮、开关、复选框或图片。 control 只能是下列其中一项:
button

object (Button)

一个按钮,用户可以点击该按钮以触发操作。

switchControl

object (SwitchControl)

一个开关 widget,用户可以点击该 widget 更改其状态并触发操作。

endIcon

object (Icon)

显示在文本之后的图标。

支持内置自定义图标。

图标

在卡片上的微件中显示的图标。如需查看 Google Chat 应用中的示例,请参阅图标

支持内置自定义图标。

JSON 表示法
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string
  // End of list of possible types for union field icons.
}
字段
altText

string

可选。用于无障碍功能的图标的说明。如果未指定,系统会提供默认值 Button。最佳实践是,设置有用的说明来说明图标的显示形式以及图标的用法(如果适用)。例如,A user's account portraitOpens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/chat

如果在 Button 中设置该图标,则当用户将鼠标悬停在该按钮上时,altText 会显示为帮助文本。不过,如果按钮也设置了 text,系统会忽略图标的 altText

imageType

enum (ImageType)

对图片应用的剪裁样式。在某些情况下,应用 CIRCLE 剪裁会导致图片的绘制尺寸大于内置图标。

联合字段 icons。卡片上的微件中显示的图标。 icons 只能是下列其中一项:
knownIcon

string

显示 Google Workspace 提供的内置图标之一。

例如,如需显示飞机图标,请指定 AIRPLANE。对于公交车,请指定 BUS

如需查看受支持图标的完整列表,请参阅内置图标

iconUrl

string

显示托管在 HTTPS 网址上的自定义图标。

例如:

"iconUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png"

支持的文件类型包括 .png.jpg

按钮

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

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

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

string

按钮内显示的文本。

icon

object (Icon)

图标图片。如果同时设置了 icontext,图标将显示在文本前面。

color

object (Color)

如果设置此标记,按钮会填充纯色背景颜色,并且字体颜色会发生变化以保持与背景颜色形成鲜明对比。例如,设置蓝色背景可能会导致生成白色文本。

如果未设置,图片背景将为白色,字体颜色为蓝色。

对于红色、绿色和蓝色,每个字段的值都是 float 数字,您可以通过两种方式来表示:介于 0 到 255 之间的数字除以 255 (153/255),或表示为 0 到 1 之间的值 (0.6)。0 表示缺少某种颜色,1 或 255/255 表示相应颜色在 RGB 刻度上完全呈现。

(可选)设置 alpha,它使用以下等式设置透明度:

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

对于 alpha1 值对应纯色,0 值对应完全透明的颜色。

例如,以下颜色表示半透明的红色:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
   "alpha": 0.5
}
onClick

object (OnClick)

必需。用户点击该按钮时要执行的操作,例如打开超链接或运行自定义函数。

disabled

boolean

如果为 true,则按钮会显示在非活动状态,并且不会响应用户操作。

altText

string

用于无障碍功能的替代文本。

设置描述性文字,让用户了解该按钮的功能。例如,如果按钮会打开一个超链接,您可以这样写:“打开新的浏览器标签页,并前往 https://developers.google.com/chat”查看 Google Chat 开发者文档。

颜色

表示 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 值一样)。

开关控制

decoratedText 微件内的切换开关样式开关或复选框。

仅在 decoratedText widget 中受支持。

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

string

在表单输入事件中标识 switch widget 的名称。

如需详细了解如何使用表单输入,请参阅接收表单数据

value

string

用户输入的值,作为表单输入事件的一部分返回。

如需详细了解如何使用表单输入,请参阅接收表单数据

selected

boolean

如果为 true,此开关处于选中状态。

onChangeAction

object (Action)

在开关状态发生更改时要执行的操作,例如要运行哪个函数。

controlType

enum (ControlType)

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

ControlType

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

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

按钮列表

水平布局的按钮列表。如需查看 Google Chat 应用中的示例,请参阅按钮列表

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

object (Button)

按钮数组。

TextInput

用户可以在其中输入文本的字段。支持建议和采用变化时触发的操作。如需查看 Google Chat 应用中的示例,请参阅文本输入

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

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

JSON 表示法
{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  },
  "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 时,建议过滤器列表仅显示 JavaJavaScript

建议值有助于引导用户输入您的应用能理解的值。在引用 JavaScript 时,某些用户可能会输入 javascript,而其他用户可能会输入 java script。建议 JavaScript 可以标准化用户与您的应用互动的方式。

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

autoCompleteAction

object (Action)

可选。指定当文本输入字段为与其互动的用户提供建议时要执行的操作。

如果未指定,建议由 initialSuggestions 设置,并由客户端处理。

如果已指定,则应用会执行此处指定的操作,例如运行自定义函数。

受 Google Workspace 插件支持,但不支持 Google Chat 应用。

placeholderText

string

当文本输入字段为空时显示在该字段中的文本。使用此文本提示用户输入一个值。例如 Enter a number from 0 to 100

受 Google Chat 应用支持,但不支持 Google Workspace 插件。

类型

文本输入字段在界面中的显示方式。例如,无论是单行输入字段还是多行输入。

如果指定了 initialSuggestions,即使 type 设置为 MULTIPLE_LINE,它也始终为 SINGLE_LINE

枚举
SINGLE_LINE 文本输入字段的固定高度为一行。
MULTIPLE_LINE 文本输入字段具有固定高度(多行)。

建议

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

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

建议值有助于引导用户输入您的应用能理解的值。在引用 JavaScript 时,某些用户可能会输入 javascript,而其他用户可能会输入 java script。建议 JavaScript 可以标准化用户与您的应用互动的方式。

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

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

object (SuggestionItem)

用于在文本输入字段中自动填充建议的建议列表。

SuggestionItem

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

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

文本输入字段的建议输入值。此值与用户输入的内容相同。

SelectionInput

一个 widget,用于创建一个或多个可供用户选择的界面项。例如,下拉菜单或复选框。您可以使用此微件来收集可预测或枚举的数据。如需查看 Google Chat 应用中的示例,请参阅选择输入

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

如需向用户收集未定义或抽象的数据,请使用 TextInput widget。

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

对于多选菜单,用户在 Chat 应用查询之前输入的文本字符数会自动填充,并在卡片上显示建议的项。

如果未指定,请将静态数据源设置为 0 个字符,将外部数据源设置为 3 个字符。

联合字段 multi_select_data_source。仅限聊天应用。对于多选菜单,数据源类型。 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 Chat 用户或聊天室)填充内容。
  • 外部数据:内容由动态外部数据源填充。

如需查看有关如何实现多选菜单的示例,请参阅 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 字段下方的文本说明或标签。

PlatformDataSource

仅限聊天应用。对于使用多选菜单的 SelectionInput widget,则为来自 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)

对于使用多选菜单的 SelectionInput widget,所有 Google Workspace 托管应用(例如 Google Workspace 组织中的用户)共享的数据源。

hostAppDataSource

object (HostAppDataSourceMarkup)

Google Workspace 托管应用独有的数据源,例如 Gmail 电子邮件、Google 日历活动或 Google Chat 消息。

CommonDataSource

仅限聊天应用。由所有 Google Workspace 宿主应用共享的数据源。

枚举
UNKNOWN 默认值。请勿使用。
USER

Google Workspace 托管应用提供的用户列表。例如,如需从 Google Chat 获取用户,请使用用户的资源名称。

格式:users/{user}

HostAppDataSourceMarkup

仅限聊天应用。对于使用多选菜单的 SelectionInput widget,即来自 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 聊天室列表。

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 聊天室的数据源。

格式:spaces/{space}

SpaceDataSource

表示 Google Chat 聊天室的数据源。

格式:spaces/{space}

JSON 表示法
{
  "defaultToCurrentSpace": boolean
}
字段
defaultToCurrentSpace

boolean

如果设为 true,系统会使用卡片的 Google Chat 聊天室作为默认选项。默认值为 false

DateTimePicker

允许用户输入日期和/或时间。如需查看 Google Chat 应用中的示例,请参阅日期时间选择器

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

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

string

在表单输入事件中标识 DateTimePicker 的名称。

如需详细了解如何使用表单输入,请参阅接收表单数据

label

string

提示用户输入日期、时间或日期和时间的文本。例如,如果用户正在安排预约,请使用 Appointment dateAppointment date and time 等标签。

type

enum (DateTimePickerType)

该 widget 是否支持输入日期、时间或日期和时间。

valueMsEpoch

string (int64 format)

微件中显示的默认值,以自 UNIX 纪元时间起的毫秒数表示。

根据选择器类型 (DateTimePickerType) 指定值:

  • DATE_AND_TIME:采用世界协调时间 (UTC) 的日历日期和时间。例如,如需表示世界协调时间 (UTC) 2023 年 1 月 1 日中午 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 中日期和时间的格式。确定用户是否可以输入日期、时间,或同时输入日期和时间。

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

分隔线

此类型没有任何字段。

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

例如,以下 JSON 会创建一个分隔线:

"divider": {}

网格

显示包含一系列项的网格。内容只能包含文字或图片。对于自适应列,或者除了文字或图片以外,您还可以使用 Columns。如需查看 Google Chat 应用中的示例,请参阅网格

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

例如,以下 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

表示网格布局中的项。项目可以包含文字和/或图片。

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

表示图片。

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

string

图片网址。

altText

string

图片的无障碍标签。

cropStyle

object (ImageCropStyle)

要应用于图片的剪裁样式。

borderStyle

object (BorderStyle)

要应用于图片的边框样式。

ImageCropStyle

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

例如,下面展示了如何应用 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

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

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

BorderStyle

卡片或微件边框的样式选项,包括边框类型和颜色。

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

enum (BorderType)

边框类型。

strokeColor

object (Color)

类型为 BORDER_TYPE_STROKE 时要使用的颜色。

cornerRadius

integer

边框的圆角半径。

BorderType

表示应用于 widget 的边框类型。

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

GridItemLayout

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

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

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

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

列并排显示。您可以使用 HorizontalSizeStyle 字段自定义每列的宽度。如果用户的屏幕宽度太窄,第二列会环绕在第一列下方:

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

如需包含 2 个以上的列或使用行,请使用 Grid widget。

Chat 应用支持,但 Google Workspace 插件不支持。

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

object (Column)

一组列。您最多可以在卡片或对话框中添加 2 列。

一列。

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)

包含在列中的微件数组。widget 会按照指定顺序显示。

HorizontalSizeStyle

指定列的填充方式。每列的宽度取决于 HorizontalSizeStyle 以及该列中微件的宽度。

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

HorizontalAlignment 枚举

指定 widget 是按列的左侧、右侧还是中心对齐。

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

VerticalAlignment 枚举

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

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

Widget

可以包含在列中的受支持的 widget。

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)
  }
  // End of list of possible types for union field data.
}
字段

联合字段 data

data 只能是下列其中一项:

textParagraph

object (TextParagraph)

TextParagraph widget。

image

object (Image)

Image widget。

decoratedText

object (DecoratedText)

DecoratedText widget。

buttonList

object (ButtonList)

ButtonList widget。

textInput

object (TextInput)

TextInput widget。

selectionInput

object (SelectionInput)

SelectionInput widget。

dateTimePicker

object (DateTimePicker)

DateTimePicker widget。

DividerStyle

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

枚举
DIVIDER_STYLE_UNSPECIFIED 请勿使用。未指定。
SOLID_DIVIDER 默认选项。在两个部分之间使用实心分隔线。
NO_DIVIDER 如果设置了此标记,各个部分之间将不会渲染分隔线。

CardAction

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

Chat 应用不支持。

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

string

显示为操作菜单项的标签。

onClick

object (OnClick)

此操作项的 onClick 操作。

CardFixedFooter

显示在卡片底部的常驻(粘性)页脚。如需查看 Google Chat 应用中的示例,请参阅卡片页脚

如果在未指定 primaryButtonsecondaryButton 的情况下设置 fixedFooter,则会导致错误。

受 Google Workspace 插件和聊天应用支持。对于聊天应用,您可以在对话框中使用固定页脚,但不能在卡片消息中使用固定页脚。

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

object (Button)

固定页脚的主按钮。该按钮必须是已设置文本和颜色的文本按钮。

secondaryButton

object (Button)

固定页脚的辅助按钮。该按钮必须是已设置文本和颜色的文本按钮。如果设置了 secondaryButton,则还必须设置 primaryButton

DisplayStyle

在 Google Workspace 插件中,决定卡片的显示方式。

Chat 应用不支持。

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