卡片
Google Chat 消息或 Google Workspace 插件中显示的卡片界面。
卡片支持定义的布局、交互式界面元素(如按钮)和富媒体(如图片)。使用卡片来展示详细信息、向用户收集信息并引导用户采取后续步骤。
如需了解如何构建卡片,请参阅以下文档:
- 对于 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 ( |
字段 | |
---|---|
header
|
卡片的标题。标头通常包含前导图片和标题。标题始终显示在卡片顶部。 |
sections[]
|
包含一组微件。每个部分都有自己的可选标题。各个部分之间用线条分隔线直观地分隔。如需查看 Google Chat 应用中的示例,请参阅卡片部分。 |
sectionDividerStyle
|
部分之间的分隔线样式。 |
cardActions[]
|
卡片的操作。操作会添加到卡片的工具栏菜单中。
由于聊天应用卡片没有工具栏,因此 Chat 应用不支持
例如,以下 JSON 使用
|
name
|
卡片的名称。用作卡片导航中的卡片标识符。 由于聊天应用不支持卡片导航,因此它们会忽略此字段。 |
fixedFooter
|
此卡片底部显示的固定页脚。
如果在未指定 受 Google Workspace 插件和聊天应用支持。对于聊天应用,您可以在对话框中使用固定页脚,但不能在卡片消息中使用固定页脚。 |
displayStyle
|
在 Google Workspace 插件中,设置 Chat 应用不支持。 |
peekCardHeader
|
显示上下文内容时,提示卡标题可充当占位符,以便用户在首页卡片和上下文卡片之间向前导航。 Chat 应用不支持。 |
CardHeader
表示卡片标题。如需查看 Google Chat 应用中的示例,请参阅卡片标头。
JSON 表示法 |
---|
{
"title": string,
"subtitle": string,
"imageType": enum (
|
字段 | |
---|---|
title
|
必需。卡片标题的标题。标题具有固定的高度:如果同时指定了标题和副标题,则标题会各占一行。如果仅指定标题,则会占用两行。 |
subtitle
|
卡片标题的副标题。如果指定,则该属性会显示在 |
imageType
|
用于剪裁图片的形状。 |
imageUrl
|
卡片标头中图片的 HTTPS 网址。 |
imageAltText
|
此图片的替代文字,用于提供无障碍功能。 |
ImageType
用于剪裁图片的形状。
枚举 | |
---|---|
SQUARE
|
默认值。为图片应用方形蒙版。例如,图片尺寸为 4x3 时变为 3x3。 |
CIRCLE
|
为图片应用圆形蒙版。例如,4x3 的图片会变成直径为 3 的圆形。 |
章节
版块包含一系列会按照指定顺序垂直呈现的 widget。
JSON 表示法 |
---|
{
"header": string,
"widgets": [
{
object (
|
字段 | |
---|---|
header
|
显示在版块顶部的文字。支持简单的 HTML 格式的文本。如需详细了解如何设置文本格式,请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。 |
widgets[]
|
版块中的所有微件。必须包含至少一个微件。 |
collapsible
|
指明此部分是否可收起。 可收起的部分会隐藏部分或所有 widget,但用户可以通过点击 Show more 来展开该部分以显示隐藏的 widget。用户可以通过点击收起再次隐藏这些微件。
如需确定哪些 widget 处于隐藏状态,请指定 |
uncollapsibleWidgetsCount
|
即使某个部分处于收起状态也仍然可见的不可折叠 widget 的数量。
例如,如果某个部分包含五个 widget 并且 |
Widget
每张卡片都由微件组成。
widget 是一种复合对象,可以表示文本、图片、按钮和其他对象类型中的一种。
JSON 表示法 |
---|
{ "horizontalAlignment": enum ( |
字段 | |
---|---|
horizontalAlignment
|
指定 widget 是按列的左侧、右侧还是中心对齐。 |
联合字段 data 。微件只能具有以下项之一。您可以使用多个 widget 字段来显示更多项。data 只能是下列其中一项:
|
|
textParagraph
|
显示文本段落。支持简单的 HTML 格式的文本。如需详细了解如何设置文本格式,请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。 例如,以下 JSON 创建了一个粗体文本:
|
image
|
显示图片。 例如,以下 JSON 会创建包含替代文本的图片:
|
decoratedText
|
显示经过装饰的文本项。 例如,以下 JSON 创建了一个显示电子邮件地址的修饰文本 widget:
|
buttonList
|
按钮列表。 例如,以下 JSON 会创建两个按钮。第一个是蓝色文本按钮,第二个是打开链接的图片按钮:
|
textInput
|
显示一个文本框,用户可在其中输入内容。 例如,以下 JSON 为电子邮件地址创建文本输入:
再比如,以下 JSON 为某种编程语言创建了一个文本输入,并提供了静态建议:
|
selectionInput
|
显示可让用户选择项目的选择控件。选择控件可以是复选框、单选按钮、开关或下拉菜单。 例如,以下 JSON 创建了一个下拉菜单,让用户能够选择大小:
|
dateTimePicker
|
显示一个微件,供用户输入日期、时间或日期和时间。 例如,以下 JSON 会创建一个日期时间选择器来安排预约:
|
divider
|
在 widget 之间显示水平线分隔线。 例如,以下 JSON 会创建一个分隔线:
|
grid
|
显示包含一系列项的网格。 网格支持任意数量的列和项。行数由项目数的上限除以列数确定。一个包含 10 个项和 2 列的网格包含 5 行。一个包含 11 个项和 2 列的网格有 6 行。 例如,以下 JSON 创建了一个包含单个项的 2 列网格:
|
columns
|
最多显示 2 列。
如需包含 2 个以上的列或使用行,请使用 例如,以下 JSON 创建了 2 列,每列包含文本段落:
|
TextParagraph
支持格式设置的文本段落。如需查看 Google Chat 应用中的示例,请参阅文本段落。如需详细了解如何设置文本格式,请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。
JSON 表示法 |
---|
{ "text": string } |
字段 | |
---|---|
text
|
显示在 widget 中的文本。 |
图片
通过网址指定且可具有 onClick
操作的图片。如需查看示例,请参阅映像。
JSON 表示法 |
---|
{
"imageUrl": string,
"onClick": {
object (
|
字段 | |
---|---|
imageUrl
|
托管映像的 HTTPS 网址。 例如:
|
onClick
|
当用户点击图片时,点击会触发此操作。 |
altText
|
此图片的替代文字,用于提供无障碍功能。 |
OnClick
表示在用户点击卡片上的互动元素(例如按钮)时如何响应。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段
|
|
action
|
如果已指定,此 |
openLink
|
如果指定,此 |
openDynamicLinkAction
|
当操作需要打开链接时,插件会触发此操作。这与上面的 |
card
|
用户点击广告后,系统会将其推送到卡片堆栈(如果已指定)。 受 Google Workspace 插件支持,但不支持 Google Chat 应用。 |
操作
描述提交表单时行为的操作。例如,您可以调用 Apps 脚本脚本来处理表单。如果触发了操作,表单值会发送到服务器。
JSON 表示法 |
---|
{ "function": string, "parameters": [ { object ( |
字段 | |
---|---|
function
|
点击或激活所包含元素时要调用的自定义函数。 如需查看用法示例,请参阅创建互动卡片。 |
parameters[]
|
操作参数列表。 |
loadIndicator
|
指定在调用相应操作时操作显示的加载指示器。 |
persistValues
|
指示表单值在操作后是否仍然存在。默认值为
如果为
如果为 |
interaction
|
可选。打开对话框时必需。 如何响应与用户的互动(例如用户点击卡片消息中的按钮)。
如果未指定,应用将通过正常方式执行
通过指定 Chat 应用支持,但 Google Workspace 插件不支持。如果为插件指定此值,系统会删除整个卡片,并且客户端中不会显示任何内容。 |
ActionParameter
调用操作方法时提供的字符串参数列表。例如,假设有三个延后按钮:“立即延后”“延后一天”或“下周延后”。您可以使用 action method = snooze()
,在字符串参数列表中传递暂停类型和暂停时间。
如需了解详情,请参阅 CommonEventObject
。
JSON 表示法 |
---|
{ "key": string, "value": string } |
字段 | |
---|---|
key
|
操作脚本的参数名称。 |
value
|
参数的值。 |
LoadIndicator
指定在调用相应操作时操作显示的加载指示器。
枚举 | |
---|---|
SPINNER
|
显示一个旋转图标,表明正在加载内容。 |
NONE
|
系统不会显示任何内容。 |
互动
可选。打开对话框时必需。
如何响应与用户的互动(例如用户点击卡片消息中的按钮)。
如果未指定,应用将通过正常方式执行 action
(例如打开链接或运行函数)进行响应。
通过指定 interaction
,应用能够以特殊的互动方式做出响应。例如,通过将 interaction
设置为 OPEN_DIALOG
,应用可以打开一个对话框。
指定后,系统不会显示加载指示器。
Chat 应用支持,但 Google Workspace 插件不支持。如果为插件指定此值,系统会删除整个卡片,并且客户端中不会显示任何内容。
枚举 | |
---|---|
INTERACTION_UNSPECIFIED
|
默认值。action 照常执行。
|
OPEN_DIALOG
|
打开一个对话框,这是一个基于窗口的卡片界面,供 Chat 应用用于与用户互动。 只有聊天应用支持响应卡片消息上的按钮点击操作。 Google Workspace 插件不支持。如果为插件指定此值,系统会删除整个卡片,并且客户端中不会显示任何内容。 |
OpenLink
表示打开超链接的 onClick
事件。
JSON 表示法 |
---|
{ "url": string, "openAs": enum ( |
字段 | |
---|---|
url
|
要打开的网址。 |
openAs
|
如何打开链接。Chat 应用不支持。 |
onClose
|
客户端是在打开链接后忘记链接,还是观察链接直至窗口关闭。Chat 应用不支持。 |
OpenAs
当 OnClick
操作打开链接时,客户端可以将其打开为完整尺寸的窗口(如果这是客户端使用的框架),或者以叠加层(例如弹出式窗口)的形式打开。具体实现取决于客户端平台的功能;如果客户端不支持,所选值可能会被忽略。
所有客户端均支持 FULL_SIZE
。
受 Google Workspace 插件支持,但不支持 Google Chat 应用。
枚举 | |
---|---|
FULL_SIZE
|
链接会以完整尺寸的窗口打开(如果客户端使用的框架就是该框架)。 |
OVERLAY
|
链接会作为叠加层(例如弹出式窗口)打开。 |
OnClose
当通过 OnClick
操作打开的链接关闭时客户端执行的操作。
具体如何实现取决于客户端平台的功能。例如,网络浏览器可能会使用 OnClose
处理程序在弹出式窗口中打开链接。
如果同时设置了 OnOpen
和 OnClose
处理程序,且客户端平台无法同时支持这两个值,则以 OnClose
为准。
受 Google Workspace 插件支持,但不支持 Google Chat 应用。
枚举 | |
---|---|
NOTHING
|
默认值。卡片不会重新加载;没有任何反应。 |
RELOAD
|
在子窗口关闭后重新加载卡片。
如果与 |
装饰文本
一个微件,用于显示带有可选装饰的文本,例如文本上方或下方的标签、文本前面的图标、选择微件或文本后面的按钮。如需查看 Google Chat 应用中的示例,请参阅装饰文本。
JSON 表示法 |
---|
{ "icon": { object ( |
字段 | |
---|---|
icon
|
已废弃,取而代之的是 |
startIcon
|
显示在文本前面的图标。 |
topLabel
|
|
text
|
必需。主要文本。 支持简单格式。如需详细了解如何设置文本格式,请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。 |
wrapText
|
自动换行设置。如果为
仅适用于 |
bottomLabel
|
|
onClick
|
当用户点击 |
联合字段 control 。显示在 decoratedText widget 中文本右侧的按钮、开关、复选框或图片。
control 只能是下列其中一项:
|
|
button
|
一个按钮,用户可以点击该按钮以触发操作。 |
switchControl
|
一个开关 widget,用户可以点击该 widget 更改其状态并触发操作。 |
endIcon
|
显示在文本之后的图标。 |
图标
在卡片上的微件中显示的图标。如需查看 Google Chat 应用中的示例,请参阅图标。
JSON 表示法 |
---|
{ "altText": string, "imageType": enum ( |
字段 | |
---|---|
altText
|
可选。用于无障碍功能的图标的说明。如果未指定,系统会提供默认值
如果在 |
imageType
|
对图片应用的剪裁样式。在某些情况下,应用 |
联合字段 icons 。卡片上的微件中显示的图标。
icons 只能是下列其中一项:
|
|
knownIcon
|
显示 Google Workspace 提供的内置图标之一。
例如,如需显示飞机图标,请指定 如需查看受支持图标的完整列表,请参阅内置图标。 |
iconUrl
|
显示托管在 HTTPS 网址上的自定义图标。 例如:
支持的文件类型包括 |
按钮
用户可以点击的文本、图标或者文本和图标按钮。如需查看 Google Chat 应用中的示例,请参阅按钮列表。
如需将图片设为可点击的按钮,请指定
(而非 Image
)并设置 ImageComponent
onClick
操作。
JSON 表示法 |
---|
{ "text": string, "icon": { object ( |
字段 | |
---|---|
text
|
按钮内显示的文本。 |
icon
|
图标图片。如果同时设置了 |
color
|
如果设置此标记,按钮会填充纯色背景颜色,并且字体颜色会发生变化以保持与背景颜色形成鲜明对比。例如,设置蓝色背景可能会导致生成白色文本。 如果未设置,图片背景将为白色,字体颜色为蓝色。
对于红色、绿色和蓝色,每个字段的值都是
(可选)设置
对于 例如,以下颜色表示半透明的红色:
|
onClick
|
必需。用户点击该按钮时要执行的操作,例如打开超链接或运行自定义函数。 |
disabled
|
如果为 |
altText
|
用于无障碍功能的替代文本。 设置描述性文字,让用户了解该按钮的功能。例如,如果按钮会打开一个超链接,您可以这样写:“打开新的浏览器标签页,并前往 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
|
颜色中的红色量,以 [0, 1] 之间的值表示。 |
green
|
颜色中的绿色量,以 [0, 1] 之间的值表示。 |
blue
|
颜色中的蓝色量,以 [0, 1] 之间的值表示。 |
alpha
|
此颜色在像素中的应用比例。也就是说,最终像素颜色由以下公式定义:
也就是说,值为 1.0 表示纯色,而值为 0.0 表示完全透明的颜色。它会使用封装容器消息,而非简单的浮动标量,以便区分默认值和未设置的值。如果省略此参数,则此颜色对象会呈现为纯色(就像明确地为 Alpha 值赋予了 1.0 值一样)。 |
开关控制
decoratedText
微件内的切换开关样式开关或复选框。
仅在 decoratedText
widget 中受支持。
JSON 表示法 |
---|
{ "name": string, "value": string, "selected": boolean, "onChangeAction": { object ( |
字段 | |
---|---|
name
|
在表单输入事件中标识 switch widget 的名称。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
value
|
用户输入的值,作为表单输入事件的一部分返回。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
selected
|
如果为 |
onChangeAction
|
在开关状态发生更改时要执行的操作,例如要运行哪个函数。 |
controlType
|
开关在界面中的显示方式。 |
ControlType
开关在界面中的显示方式。
枚举 | |
---|---|
SWITCH
|
切换开关样式的开关。 |
CHECKBOX
|
已废弃,取而代之的是 CHECK_BOX 。
|
CHECK_BOX
|
复选框。 |
按钮列表
水平布局的按钮列表。如需查看 Google Chat 应用中的示例,请参阅按钮列表。
JSON 表示法 |
---|
{
"buttons": [
{
object (
|
字段 | |
---|---|
buttons[]
|
按钮数组。 |
TextInput
用户可以在其中输入文本的字段。支持建议和采用变化时触发的操作。如需查看 Google Chat 应用中的示例,请参阅文本输入。
在表单输入事件期间,聊天应用会接收并处理所输入文本的值。如需详细了解如何使用表单输入,请参阅接收表单数据。
如果您需要向用户收集未定义或抽象的数据,请使用文本输入。如需向用户收集已定义或枚举的数据,请使用 SelectionInput
widget。
JSON 表示法 |
---|
{ "name": string, "label": string, "hintText": string, "value": string, "type": enum ( |
字段 | |
---|---|
name
|
在表单输入事件中标识文本输入的名称。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
label
|
界面中文本输入字段上方显示的文本。
指定有助于用户输入应用所需信息的文本。例如,如果您想询问某人的姓名,但特别需要其姓氏,请输入
如果未指定 |
hintText
|
显示在文本输入字段下方的文本,旨在通过提示用户输入特定值来为用户提供帮助。此文本始终可见。
如果未指定 |
value
|
用户输入的值,作为表单输入事件的一部分返回。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
type
|
文本输入字段在界面中的显示方式。例如,字段是单行还是多行。 |
onChangeAction
|
当文本输入字段中发生变化时该怎么做。例如,用户在字段中添加内容或删除文本。 可执行的操作示例包括在 Google Chat 中运行自定义函数或打开对话框。 |
initialSuggestions
|
用户可以输入的建议值。当用户在文本输入字段内点击时,系统会显示这些值。当用户输入内容时,建议值会动态进行过滤,以匹配用户输入的内容。
例如,编程语言的文本输入字段可能会建议 Java、JavaScript、Python 和 C++。当用户开始输入
建议值有助于引导用户输入您的应用能理解的值。在引用 JavaScript 时,某些用户可能会输入
指定后, |
autoCompleteAction
|
可选。指定当文本输入字段为与其互动的用户提供建议时要执行的操作。
如果未指定,建议由 如果已指定,则应用会执行此处指定的操作,例如运行自定义函数。 受 Google Workspace 插件支持,但不支持 Google Chat 应用。 |
placeholderText
|
当文本输入字段为空时显示在该字段中的文本。使用此文本提示用户输入一个值。例如 受 Google Chat 应用支持,但不支持 Google Workspace 插件。 |
类型
文本输入字段在界面中的显示方式。例如,无论是单行输入字段还是多行输入。
如果指定了 initialSuggestions
,即使 type
设置为 MULTIPLE_LINE
,它也始终为 SINGLE_LINE
。
枚举 | |
---|---|
SINGLE_LINE
|
文本输入字段的固定高度为一行。 |
MULTIPLE_LINE
|
文本输入字段具有固定高度(多行)。 |
建议
用户可以输入的建议值。当用户在文本输入字段内点击时,系统会显示这些值。当用户输入内容时,建议值会动态进行过滤,以匹配用户输入的内容。
例如,编程语言的文本输入字段可能会建议 Java、JavaScript、Python 和 C++。当用户开始输入 Jav
时,建议过滤条件列表会显示 Java
和 JavaScript
。
建议值有助于引导用户输入您的应用能理解的值。在引用 JavaScript 时,某些用户可能会输入 javascript
,而其他用户可能会输入 java script
。建议 JavaScript
可以标准化用户与您的应用互动的方式。
指定后,TextInput.type
始终为 SINGLE_LINE
,即使将其设置为 MULTIPLE_LINE
也是如此。
JSON 表示法 |
---|
{
"items": [
{
object (
|
字段 | |
---|---|
items[]
|
用于在文本输入字段中自动填充建议的建议列表。 |
SuggestionItem
用户可以在文本输入字段中输入一个建议值。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段
|
|
text
|
文本输入字段的建议输入值。此值与用户输入的内容相同。 |
SelectionInput
一个 widget,用于创建一个或多个可供用户选择的界面项。例如,下拉菜单或复选框。您可以使用此微件来收集可预测或枚举的数据。如需查看 Google Chat 应用中的示例,请参阅选择输入。
聊天应用可以处理用户选择或输入的内容的价值。如需详细了解如何使用表单输入,请参阅接收表单数据。
如需向用户收集未定义或抽象的数据,请使用 TextInput
widget。
JSON 表示法 |
---|
{ "name": string, "label": string, "type": enum ( |
字段 | |
---|---|
name
|
用于标识表单输入事件中的选择输入的名称。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
label
|
界面中选择输入字段上方显示的文本。 指定有助于用户输入应用所需信息的文本。例如,如果用户从下拉菜单中选择工作工单的紧急程度,则标签可以是“紧急程度”或“选择紧急程度”。 |
type
|
在 |
items[]
|
可选项的数组。例如,单选按钮或复选框的数组。最多支持 100 项内容。 |
onChangeAction
|
如果已指定,则在更改选择时提交表单。如果未指定,则必须指定一个用于提交表单的单独按钮。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
multiSelectMaxSelectedItems
|
对于多选菜单,这是指用户可以选择的最大项数。最小值为 1 项。如果未指定,则设置为 3 项。
|
multiSelectMinQueryLength
|
对于多选菜单,用户在 Chat 应用查询之前输入的文本字符数会自动填充,并在卡片上显示建议的项。 如果未指定,请将静态数据源设置为 0 个字符,将外部数据源设置为 3 个字符。
|
联合字段 multi_select_data_source 。仅限聊天应用。对于多选菜单,数据源类型。
multi_select_data_source 只能是下列其中一项:
|
|
externalDataSource
|
外部数据源,例如关系型数据库。
|
platformDataSource
|
来自 Google Workspace 托管应用的数据源。
|
SelectionType
用户可以选择的内容的格式。不同的选项支持不同类型的互动。例如,用户可以选中多个复选框,但只能从下拉菜单中选择一项。
每个选择输入都支持一种选择类型。例如,系统不支持将复选框和开关混用。
枚举 | |
---|---|
CHECK_BOX
|
一组复选框。用户可以选中一个或多个复选框。 |
RADIO_BUTTON
|
一组单选按钮。用户可以选择一个单选按钮。 |
SWITCH
|
一组开关。用户可以开启一个或多个开关。 |
DROPDOWN
|
下拉菜单。用户可以从菜单中选择一项。 |
MULTI_SELECT
|
Chat 应用支持,但 Google Workspace 插件不支持。 静态或动态数据的多选菜单。用户可从菜单栏中选择一个或多个项。用户还可以输入值来填充动态数据。例如,用户可以开始输入 Google Chat 聊天室的名称,而微件会自动建议聊天室。 要为多选菜单填充内容,您可以使用下列其中一种数据源:
如需查看有关如何实现多选菜单的示例,请参阅
|
SelectionItem
用户可以在选择输入(例如复选框或开关)中选择的项。
JSON 表示法 |
---|
{ "text": string, "value": string, "selected": boolean, "startIconUri": string, "bottomText": string } |
字段 | |
---|---|
text
|
用于向用户标识商品或描述商品的文本。 |
value
|
与该商品相关的值。客户端应将其用作表单输入值。 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
selected
|
默认情况下,项目是否处于选中状态。如果选择输入仅接受一个值(例如单选按钮或下拉菜单),请仅为一项设置此字段。 |
startIconUri
|
对于多选菜单,是在项目的
|
bottomText
|
对于多选菜单,这是显示在该项的
|
PlatformDataSource
仅限聊天应用。对于使用多选菜单的
widget,则为来自 Google Workspace 托管应用的数据。用于填充多选菜单中的项。
SelectionInput
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 data_source 。数据源。
data_source 只能是下列其中一项:
|
|
commonDataSource
|
对于使用多选菜单的
|
hostAppDataSource
|
Google Workspace 托管应用独有的数据源,例如 Gmail 电子邮件、Google 日历活动或 Google Chat 消息。
|
CommonDataSource
仅限聊天应用。由所有 Google Workspace 宿主应用共享的数据源。
枚举 | |
---|---|
UNKNOWN
|
默认值。请勿使用。 |
USER
|
Google Workspace 托管应用提供的用户列表。例如,如需从 Google Chat 获取用户,请使用用户的资源名称。 格式:users/{user}
|
HostAppDataSourceMarkup
仅限聊天应用。对于使用多选菜单的
widget,即来自 Google Workspace 托管应用的数据源。SelectionInput
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 data_source 。为多选菜单获取数据的 Google Workspace 应用。data_source 只能是下列其中一项:
|
|
chatDataSource
|
数据源为 Google Chat。
|
ChatClientDataSourceMarkup
仅限聊天应用。对于使用多选菜单的
微件(来自 Google Chat 的数据源)。例如,用户所属的 Google Chat 聊天室列表。
SelectionInput
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 source 。Google Chat 数据源。
source 只能是下列其中一项:
|
|
spaceDataSource
|
表示 Google Chat 聊天室的数据源。 格式:spaces/{space}
|
SpaceDataSource
表示 Google Chat 聊天室的数据源。
格式:spaces/{space}
JSON 表示法 |
---|
{ "defaultToCurrentSpace": boolean } |
字段 | |
---|---|
defaultToCurrentSpace
|
如果设为
|
DateTimePicker
允许用户输入日期和/或时间。如需查看 Google Chat 应用中的示例,请参阅日期时间选择器。
用户可以输入文本或使用选择器选择日期和时间。如果用户输入的日期或时间无效,选择器会显示错误,提示用户正确输入信息。
JSON 表示法 |
---|
{ "name": string, "label": string, "type": enum ( |
字段 | |
---|---|
name
|
在表单输入事件中标识 如需详细了解如何使用表单输入,请参阅接收表单数据。 |
label
|
提示用户输入日期、时间或日期和时间的文本。例如,如果用户正在安排预约,请使用 |
type
|
该 widget 是否支持输入日期、时间或日期和时间。 |
valueMsEpoch
|
微件中显示的默认值,以自 UNIX 纪元时间起的毫秒数表示。
根据选择器类型 (
|
timezoneOffsetDate
|
表示时区与世界协调时间 (UTC) 的偏移量的数字(以分钟为单位)。如果设置此参数,则 |
onChangeAction
|
当用户从 |
DateTimePickerType
DateTimePicker
widget 中日期和时间的格式。确定用户是否可以输入日期、时间,或同时输入日期和时间。
枚举 | |
---|---|
DATE_AND_TIME
|
用户输入日期和时间。 |
DATE_ONLY
|
用户输入日期。 |
TIME_ONLY
|
用户输入时间。 |
分隔线
此类型没有任何字段。
以水平线的形式显示微件之间的分隔线。如需查看 Google Chat 应用中的示例,请参阅分隔线。
例如,以下 JSON 会创建一个分隔线:
"divider": {}
网格
显示包含一系列项的网格。内容只能包含文字或图片。对于自适应列,或者除了文字或图片以外,您还可以使用
。如需查看 Google Chat 应用中的示例,请参阅网格。
Columns
网格支持任意数量的列和项。行数由项目数除以列数决定。一个包含 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 ( |
字段 | |
---|---|
title
|
网格标题中显示的文本。 |
items[]
|
要在网格中显示的项。 |
borderStyle
|
要应用于每个网格项的边框样式。 |
columnCount
|
要在网格中显示的列数。如果未指定此字段,系统会使用默认值,并且该默认值因网格的显示位置(对话框与随播广告)而异。 |
onClick
|
每个网格项都会重复使用此回调,但会将项在项列表中的标识符和索引添加到回调的参数中。 |
GridItem
表示网格布局中的项。项目可以包含文字和/或图片。
JSON 表示法 |
---|
{ "id": string, "image": { object ( |
字段 | |
---|---|
id
|
此网格项的用户指定的标识符。此标识符会在父网格的 |
image
|
网格项中显示的图片。 |
title
|
网格项的标题。 |
subtitle
|
网格项的副标题。 |
layout
|
要用于网格项的布局。 |
ImageComponent
表示图片。
JSON 表示法 |
---|
{ "imageUri": string, "altText": string, "cropStyle": { object ( |
字段 | |
---|---|
imageUri
|
图片网址。 |
altText
|
图片的无障碍标签。 |
cropStyle
|
要应用于图片的剪裁样式。 |
borderStyle
|
要应用于图片的边框样式。 |
ImageCropStyle
表示应用于图片的剪裁样式。
例如,下面展示了如何应用 16:9 的宽高比:
cropStyle {
"type": "RECTANGLE_CUSTOM",
"aspectRatio": 16/9
}
JSON 表示法 |
---|
{
"type": enum (
|
字段 | |
---|---|
type
|
剪裁类型。 |
aspectRatio
|
如果剪裁类型为 例如,下面展示了如何应用 16:9 的宽高比:
|
ImageCropType
表示应用于图片的剪裁样式。
枚举 | |
---|---|
IMAGE_CROP_TYPE_UNSPECIFIED
|
请勿使用。未指定。 |
SQUARE
|
默认值。应用方形剪裁。 |
CIRCLE
|
应用圆形剪裁。 |
RECTANGLE_CUSTOM
|
按照自定义宽高比应用矩形剪裁。使用 aspectRatio 设置自定义宽高比。 |
RECTANGLE_4_3
|
应用宽高比为 4:3 的矩形剪裁。 |
BorderStyle
卡片或微件边框的样式选项,包括边框类型和颜色。
JSON 表示法 |
---|
{ "type": enum ( |
字段 | |
---|---|
type
|
边框类型。 |
strokeColor
|
类型为 |
cornerRadius
|
边框的圆角半径。 |
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 个以上的列或使用行,请使用
widget。
Grid
Chat 应用支持,但 Google Workspace 插件不支持。
JSON 表示法 |
---|
{
"columnItems": [
{
object (
|
字段 | |
---|---|
columnItems[]
|
一组列。您最多可以在卡片或对话框中添加 2 列。 |
列
一列。
JSON 表示法 |
---|
{ "horizontalSizeStyle": enum ( |
字段 | |
---|---|
horizontalSizeStyle
|
指定列的填充方式。 |
horizontalAlignment
|
指定 widget 是按列的左侧、右侧还是中心对齐。 |
verticalAlignment
|
指定 widget 是与列的顶部、底部对齐还是居中对齐。 |
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 |
字段 | |
---|---|
联合字段
|
|
textParagraph
|
|
image
|
|
decoratedText
|
|
buttonList
|
|
textInput
|
|
selectionInput
|
|
dateTimePicker
|
|
DividerStyle
卡片的分隔线样式。目前仅用于卡片部分之间的分隔线。
枚举 | |
---|---|
DIVIDER_STYLE_UNSPECIFIED
|
请勿使用。未指定。 |
SOLID_DIVIDER
|
默认选项。在两个部分之间使用实心分隔线。 |
NO_DIVIDER
|
如果设置了此标记,各个部分之间将不会渲染分隔线。 |
CardAction
卡片操作是指与卡片相关联的操作。例如,账单卡片可能包含删除账单、通过电子邮件发送账单或在浏览器中打开账单等操作。
Chat 应用不支持。
JSON 表示法 |
---|
{
"actionLabel": string,
"onClick": {
object (
|
字段 | |
---|---|
actionLabel
|
显示为操作菜单项的标签。 |
onClick
|
此操作项的 |
DisplayStyle
在 Google Workspace 插件中,决定卡片的显示方式。
Chat 应用不支持。
枚举 | |
---|---|
DISPLAY_STYLE_UNSPECIFIED
|
请勿使用。未指定。 |
PEEK
|
卡片的标题显示在边栏底部,部分覆盖堆栈的当前顶部卡片。点击标题会将卡片弹出卡片堆栈。如果卡片没有标头,系统会使用生成的标头。 |
REPLACE
|
默认值。通过替换卡片堆栈中顶部卡片的视图来显示卡片。 |