Package google.apps.card.v1

string

点击或激活包含的元素时要调用的自定义函数。

如需查看用法示例，请参阅创建互动卡片。

ActionParameter

操作参数列表。

LoadIndicator

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

bool

指示表单值在操作后是否仍然存在。默认值为 false。

如果为 true，则表单值会在操作触发后保留。如需允许用户在操作处理期间进行更改，请将 LoadIndicator 设置为 NONE。对于 Chat 应用中的卡片消息，您还必须将操作的 ResponseType 设置为 UPDATE_MESSAGE，并使用包含该操作的卡片中的相同 card_id。

如果为 false，则系统会在触发操作时清除表单值。如需阻止用户在操作期间进行更改，请将 LoadIndicator 设置为 SPINNER。

Interaction

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

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

如果未指定，应用将通过照常执行 action（例如打开链接或运行函数）进行响应。

通过指定 interaction，应用能够以特殊的互动方式做出响应。例如，通过将 interaction 设置为 OPEN_DIALOG，应用可以打开对话框。指定后，系统不会显示加载指示器。

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

string

操作脚本的参数名称。

string

参数的值。

BorderType

边框类型。

Color

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

int32

边框的圆角半径。

string

按钮内显示的文本。

Icon

图标图片。如果同时设置了 icon 和 text，图标将显示在文本前面。

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)

对于 alpha，1 值对应纯色，0 值对应完全透明的颜色。

例如，以下颜色表示半透明的红色：

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

OnClick

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

bool

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

string

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

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

Button

按钮数组。

CardHeader

卡片的标题。标头通常包含前导图片和标题。标题始终显示在卡片顶部。

Section

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

DividerStyle

部分之间的分隔线样式。

CardAction

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

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

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

string

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

由于 Chat 应用不支持卡片导航，因此会忽略此字段。

CardFixedFooter

此卡片底部显示的固定页脚。

如果在未指定 primaryButton 或 secondaryButton 的情况下设置 fixedFooter，则会导致错误。

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

DisplayStyle

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

Chat 应用不支持。

CardHeader

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

Chat 应用不支持。

string

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

OnClick

此操作项的 onClick 操作。

Button

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

Button

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

string

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

string

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

ImageType

用于剪裁图片的形状。

string

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

string

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

string

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

Widget

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

bool

指明此部分是否可收起。

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

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

int32

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

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

Column

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

HorizontalSizeStyle

指定列的填充方式。

HorizontalAlignment

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

VerticalAlignment

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

Widgets

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

TextParagraph

TextParagraph微件。

Image

Image微件。

DecoratedText

DecoratedText微件。

ButtonList

ButtonList微件。

TextInput

TextInput微件。

SelectionInput

SelectionInput微件。

DateTimePicker

DateTimePicker微件。

string

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

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

string

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

DateTimePickerType

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

int64

微件中显示的默认值（以自 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）。

int32

表示时区与世界协调时间 (UTC) 的偏移量的数字（以分钟为单位）。如果设置此标记，value_ms_epoch 会以指定的时区显示。如果未设置，值默认采用用户的时区设置。

Action

当用户从 DateTimePicker 界面中点击保存或清除时触发。

Icon

已废弃，取而代之的是 startIcon。

Icon

显示在文本前面的图标。

string

text 上方显示的文本。一律截断。

string

必需。主要文本。

支持简单格式。如要详细了解如何设置文本格式，请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。

bool

自动换行设置。如果为 true，文本会换行并分行显示。否则，文本将被截断。

仅适用于 text，而不适用于 topLabel 和 bottomLabel。

string

text 下方显示的文本。一律换行。

OnClick

当用户点击 topLabel 或 bottomLabel 时，就会触发此操作。

Button

用户可以点击以触发操作的按钮。

SwitchControl

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

Icon

显示在文本之后的图标。

支持内置和自定义图标。

string

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

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

string

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

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

bool

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

Action

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

ControlType

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

Suggestions

string

这是空操作架构字段，可能出现在用于语法检查的标记中。

string

网格标题中显示的文本。

GridItem

要在网格中显示的项。

BorderStyle

要应用于每个网格项的边框样式。

int32

要在网格中显示的列数。如果未指定此字段，系统会使用默认值，且该默认值因网格的显示位置（对话框与随播广告）而异。

OnClick

每个网格项都会重复使用此回调，但会将项的标识符和项在列表项中的索引添加到回调的参数中。

string

此网格项的用户指定的标识符。此标识符会在父网格的 onClick 回调参数中返回。

ImageComponent

在网格项中显示的图片。

string

网格项的标题。

string

网格项的副标题。

GridItemLayout

要用于网格项的布局。

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/chat。

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

ImageType

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

string

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

例如，如需显示飞机图标，请指定 AIRPLANE。如果是公交车，请指定 BUS。

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

string

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

例如：

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

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

string

托管映像的 HTTPS 网址。

例如：

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

OnClick

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

string

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

string

图片网址。

string

图片的无障碍标签。

ImageCropStyle

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

BorderStyle

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

ImageCropType

剪裁类型。

double

如果剪裁类型为 RECTANGLE_CUSTOM，要使用的宽高比。

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

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

string

要返回到插件的链接的网址。

string

要返回到插件的链接的标题。

Card

一张卡片，显示来自第三方服务的链接的相关信息。

string

在用于链接预览的智能条状标签中显示的标题。如果未设置，智能条状标签会显示 preview_card 的标题。

string

在链接预览中显示的标题。如果此政策未设置，链接预览中会显示 preview_card 的标头。

bool

卡片堆栈会弹出除根卡以外的所有卡片。

bool

卡片堆叠会弹出一张卡片。

string

卡片堆栈会弹出具有指定卡片名称的指定卡片上方的所有卡片。

Card

卡片堆叠将一张卡片推送到卡片堆叠。

Card

卡片堆栈会使用新卡片更新顶部的卡片，并保留已填充的表单字段值。对于非等效字段，该值会被丢弃。

string

为通知显示的纯文本，不带 HTML 标记。

Action

如果已指定，则此 onClick 会触发操作。

OpenLink

如果指定，此 onClick 会触发打开链接操作。

Action

当操作需要打开链接时，插件会触发此操作。这与上面的 open_link 不同，因为它需要与服务器通信以获取链接。因此，在打开链接操作响应返回之前，Web 客户端需要做一些准备工作。受 Google Workspace 插件支持，但不支持 Google Chat 应用。

Card

点击相应新卡片后，系统会将其推送到卡片堆栈（如果已指定）。

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

string

要打开的网址。

OpenAs

如何打开链接。Chat 应用不支持。

OnClose

客户端是在打开链接后忘记链接，还是观察链接直至窗口关闭。Chat 应用不支持。

Action

HostAppActionMarkup

由各个托管应用处理的操作。

string

这是空操作架构字段，可能出现在用于语法检查的标记中。

Navigation

推送、弹出或更新显示的卡片。

OpenLink

立即在新标签页或弹出式窗口中打开目标链接。

Notification

向最终用户显示通知。

LinkPreview

向最终用户显示链接预览。

Link

在 Google Workspace 应用内创建的第三方资源的链接。格式设为包含一项内容的对象数组。数组中的所有其他项都会被忽略。

string

用于标识表单输入事件中的选择输入的名称。

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

string

界面中选择输入字段上方显示的文本。

指定有助于用户输入应用所需信息的文本。例如，如果用户从下拉菜单中选择工作工单的紧急程度，则标签可以是“紧急程度”或“选择紧急程度”。

SelectionType

在 SelectionInput widget 中向用户显示的项目类型。选择类型支持不同类型的互动。例如，用户可以选中一个或多个复选框，但只能从下拉菜单中选择一个值。

SelectionItem

可选项的数组。例如，单选按钮或复选框的数组。最多支持 100 项内容。

Action

如果已指定，则在更改选择时提交表单。如果未指定，则必须指定一个用于提交表单的单独按钮。

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

int32

对于多选菜单，这是指用户可以选择的最大项数。最小值为 1 项。如果未指定，则默认为 3 项。

int32

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

如果未指定，静态数据源默认为 0 个字符，外部数据源默认为 3 个字符。

Action

外部数据源，例如关系型数据库。

PlatformDataSource

Google Workspace 中的数据源。

CommonDataSource

所有 Google Workspace 应用（例如 Google Workspace 组织中的用户）共享的数据源。

HostAppDataSourceMarkup

Google Workspace 托管应用（例如 Google Chat 中的聊天室）独有的数据源。

string

用于向用户标识商品或描述商品的文本。

string

与该商品相关的值。客户端应将其用作表单输入值。

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

bool

默认情况下，项目是否处于选中状态。如果选择输入仅接受一个值（例如单选按钮或下拉菜单），请仅为一项设置此字段。

string

对于多选菜单，是在项目的 text 字段旁边显示的图标的网址。支持 PNG 和 JPEG 文件。必须是 HTTPS 网址。例如 https://developers.google.com/chat/images/quickstart-app-avatar.png。

string

对于多选菜单，显示相应内容的 text 字段下方的文本说明或标签。

RenderActions

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

bool

卡片的状态是否已发生变化，以及现有卡片中的数据是否已过时。

string

这是一个空操作架构字段，可能出现在用于语法检查的标记中。

SuggestionItem

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

string

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

string

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

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

string

界面中文本输入字段上方显示的文本。

指定有助于用户输入应用所需信息的文本。例如，如果您要询问某人的姓名，但特别需要其姓氏，请输入 surname，而不是 name。

如果 hintText 未指定，则为必需。否则，为可选。

string

显示在文本输入字段下方的文本，旨在通过提示用户输入特定值来为用户提供帮助。此文本始终可见。

如果 label 未指定，则为必需。否则，为可选。

string

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

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

Type

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

Action

当文本输入字段中发生变化时该怎么做。例如，用户在字段中添加内容或删除文本。

可执行的操作示例包括运行自定义函数或在 Google Chat 中打开对话框。

Suggestions

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

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

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

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

Action

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

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

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

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

string

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

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

string

微件中显示的文本。

HorizontalAlignment

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

TextParagraph

显示文本段落。支持简单的 HTML 格式的文本。如要详细了解如何设置文本格式，请参阅设置 Google Chat 应用中的文本格式和设置 Google Workspace 插件中的文本格式。

例如，以下 JSON 会创建粗体文本：

"textParagraph": {
  "text": "  <b>bold text</b>"
}

Image

显示图片。

例如，以下 JSON 会创建包含替代文本的图片：

"image": {
  "imageUrl":
  "https://developers.google.com/chat/images/quickstart-app-avatar.png",
  "altText": "Chat app avatar"
}

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

按钮列表。

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

显示一个文本框，用户可在其中输入内容。

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

显示可让用户选择项目的选择控件。选择控件可以是复选框、单选按钮、开关或下拉菜单。

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

显示一个微件，供用户输入日期、时间或日期和时间。

例如，以下 JSON 会创建一个用于安排预约的日期时间选择器：

"dateTimePicker": {
  "name": "appointment_time",
  "label": "Book your appointment at:",
  "type": "DATE_AND_TIME",
  "valueMsEpoch": "796435200000"
}

Divider

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

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

"divider": {
}

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

最多可显示 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"
          }
        }
      ]
    }
  ]
}