为 Google Chat 应用构建卡片

本页介绍了如何构建卡片的组件和结构。卡片是 Google Chat 应用可用于向 Chat 用户显示和收集信息的界面。Chat 应用可以在以下界面中构建和显示卡片：

  • 包含一个或多个卡片的消息。
  • 首页，这是 Chat 应用私信中的首页标签页中显示的卡片。
  • 对话框：即从消息和首页在新窗口中打开的卡片。

在本页中，您将了解卡片的以下组成部分：

  • 标题，通常包含卡片或卡片部分的标题。
  • 版块，用于构成卡片的主要正文，包括 widget 和其他互动元素。在卡片部分中，您可以为卡片添加更多结构，包括列和网格。
  • 固定页脚：显示在对话框底部，用于显示按钮等持久性界面元素。

前提条件

启用了交互功能的 Google Chat 应用。如需创建交互式 Chat 应用，请根据您要使用的应用架构完成以下任一快速入门：

使用卡片制作工具设计和预览 Chat 应用的消息和界面：

打开卡片制作工具

添加标头

CardHeader widget 表示卡片的标题。标题可以包含卡片的标题、副标题和头像图片。

以下是 CardHeader 的示例：

添加一个或多个卡片版块

CardSection 微件是卡片中的高级容器。您可以使用卡片部分在卡片中对 widget 进行分组。对于每个卡片部分，您可以添加一个标题和一个或多个微件。

以下是一个包含两个 textParagraph widget 的 CardSection 示例：

在 widget 之间添加水平分隔线

divider 微件会在垂直堆叠的微件之间显示一条横线，横线跨越卡片的宽度。该线条是一种视觉分隔线，可帮助用户区分各个 widget，让卡片更易于浏览和理解。

以下卡片由其他类型的 widget 之间的 divider widget 组成：

添加列

columns widget 在一个卡片中最多可显示 2 列。您可以向每列添加微件；微件会按指定的顺序显示。如需添加超过 2 列或使用行，请使用 grid widget。

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

以下示例显示了一个包含 2 列文本的 columns 微件的卡片。如需仅查看列布局并收起代码示例，请点击 Collapse。当空间受限时（如以下示例所示），第二列会换行到第一列下方。

定义列宽

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

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

以下示例显示了一个包含 columns 微件的卡片，其中包含 2 列文本，每列包含 4 项。列中的每个项都应用了 horizontalSizeStyle，以便控制文本填充每个列的空间量：

  • 第一个文本段落使用 FILL_MINIMUM_SPACE 填充的宽度不得超过卡片宽度的 30%。
  • 第二个文本段落使用 FILL_AVAILABLE_SPACE 填充卡片宽度中的可用空间。在此示例中，它会填充卡片宽度的 70%。
  • 第三个文本段落未定义 horizontalSizeStyle，因此默认会填充卡片可用空间。
  • 第四个文本段落使用 FILL_MINIMUM_SPACE 填充的宽度不得超过卡片宽度的 30%。

定义列的水平对齐方式

您可以通过定义 horizontalAligment 字段，将 widget 水平对齐到列的左侧、右侧或居中。如果 horizontalAlignment 字段未定义，则 widget 会在列中对齐到左侧。

以下示例将列中的文本水平对齐到左侧：

以下示例会将列中的文本水平对齐到中心：

以下示例将列中的文本水平对齐到右侧：

定义列的垂直对齐方式

您可以通过定义 verticalAlignment 字段，将 widget 垂直对齐到列的顶部、底部或中心。如果 verticalAlignment 字段未定义，则列中的 widget 会对齐到顶部。

以下示例将列中的文本垂直对齐到顶部：

以下示例会将列中的文本垂直居中对齐：

以下示例将列中的文本垂直对齐到底部：

添加网格以显示一组项

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

该 widget 支持建议，可帮助用户输入统一的数据，还支持更改时执行的操作，即在文本输入字段发生更改（例如用户添加或删除文本）时运行的 Actions。

以下示例是一个包含单个项的 2 列网格：

如需定义文本在网格中与图片一起显示的位置，您可以指定 gridItemLayout 字段。借助此字段，您可以指定文本是在网格中项的上方还是下方显示。如果 gridItemLayout 未定义，文本默认显示在网格中的项下方。

以下示例是一个三列网格，每个网格中都包含文字和图片。第一个网格用于定义要在图片上方显示的文本，第二个网格用于定义要在图片下方显示的文本，第三个网格不用于定义文本的位置。

为网格或列添加边框

对于显示在 column 或 grid widget 中的项，您可以通过定义 borderType 字段和 borderStyle 字段，为这些界面元素添加边框。如果未定义 borderStyle 字段，则默认不显示边框。您可以定义要应用于微件中所有项的 borderType，也可以将样式应用于微件中的每个单独项。

以下示例是一个 2 列网格，每个网格中都有一张图片，其中边框类型、样式和颜色已定义为应用于网格中的所有项。

以下示例是一个 3 列网格，每个网格中都有一张图片，边框样式和类型单独定义。第一个图片的边框定义为 STROKE。第二张图片的边框定义为 NO_BORDER。第三张图片未定义边框。

CardFixedFooter 微件表示 Chat 应用发送的对话框消息的页脚。页脚可以包含一个主按钮和一个辅助按钮。

CardFixedFooter 微件仅适用于对话框。

以下是一个包含两个按钮的 CardFixedFooter widget 示例：

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”消息。或“无法处理您的请求”。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，但当 Chat 应用的错误日志记录功能处于开启状态时，描述性错误消息和日志数据可帮助您修正错误。如需有关查看、调试和修复错误的帮助，请参阅排查和修复 Google Chat 错误。