本页介绍了如何在卡片或对话框消息中设置 widget 的格式和结构。
使用卡片构建器设计和预览 Chat 应用的 JSON 卡片消息:
打开卡片制作工具前提条件
在列中显示卡片和对话框
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 错误。
相关主题
columns
horizontalSizeStyle
horizontalAligment
verticalAlignment
divider
grid
gridItemLayout
borderStyle
borderType