设置卡片或对话框的结构

本页介绍了如何在卡片或对话框消息中设置 widget 的格式和结构。

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

打开卡片制作工具

前提条件

  • 有权访问 Google Chat 的 Google Workspace 帐号。
  • 一款已发布的 Chat 应用。如需构建 Chat 应用，请按照此quickstart操作。

    • 在列中显示卡片和对话框

    columns widget 在卡片或对话框中最多显示 2 列。您可以在每一列中添加 widget；这些 widget 会按照指定顺序显示。如需包含 2 个以上的列或使用行，请使用 grid widget。

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

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

    定义列宽

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

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

    以下示例显示了一张包含 columns widget 的卡片，该 widget 包含 2 列文本，1 列包含 4 个项。列中的每一项都应用了 horizontalSizeStyle，以便操纵文本在每列中占多大空间：

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

    定义列的水平对齐方式

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

    以下示例将一列中的文本左对齐：

    以下示例将一列中的文本居中对齐：

    以下示例将一列中的文本右对齐：

    定义列的垂直对齐方式

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

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

    以下示例将一列中的文本居中对齐：

    以下示例会在底部垂直对齐一列内的文本：

    在微件之间添加水平分隔线

    divider widget 在垂直堆叠的 widget 之间显示一条跨越卡片宽度的水平线。这条线是一种视觉分隔线，有助于用户区分各个 widget，使卡片更易于浏览和理解。

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

    显示包含一系列项的网格

    grid widget 会显示一个包含一系列项的网格。网格支持任意数量的列和项。行数由项目数除以列数确定。一个包含 10 个项和 2 列的网格有 5 行。一个包含 11 个项和 2 列的网格有 6 行。

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

    以下示例是一个包含两个列的网格，其中只包含一个项：

    通过图片在网格中指定文本的显示位置

    通过 gridItemLayout 字段，您可以在每个 gridItem 中定义文本是显示在网格中的项上方还是下方。如果未定义 gridItemLayout，文本默认显示在网格中的项下方

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

    为界面元素添加边框

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

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

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

    问题排查

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

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