本指南介绍了您可能遇到的与卡片相关的常见错误及解决方法。
使用卡片制作工具设计和预览卡片。
打开卡片制作工具卡片错误的显示方式
卡片错误会以以下几种方式呈现：
- 卡片的某些部分（例如微件或组件）不会以非预期方式显示或呈现。
- 整张卡片也不会显示。
- 对话框关闭、无法打开或无法加载。
如果您遇到此类行为，则表示应用的卡片有误。
参考信息：有效的无错误卡片消息和对话框
在检查错误的卡片示例之前，请先考虑这张有效的卡片消息和对话框。为说明每个示例错误及其修复方法，我们通过引入错误修改了此卡片的 JSON。
无错误的卡消息
下面是有效的无错卡片消息，其中详细说明了联系信息，其中包含标题、部分以及装饰文本和按钮等 widget：
无错误的对话框
下面展示了这个无错的有效对话框，它通过向用户收集信息、显示页脚、文本输入、开关以及按钮等可编辑 widget 来创建联系人：
错误：卡片的部分内容未显示
有时，卡片会渲染，但您想看到的卡片部分却没有显示；可能的原因如下：
- 缺少必填的 JSON 字段。
- JSON 字段拼写错误或大小写错误。
原因：缺少必需的 JSON 字段
此示例错误中缺少必需的 JSON 字段 title。因此，卡片可以呈现，但本应显示的部分却没有。如果省略必填字段，可能很难预测卡片的呈现效果。
如需修正此错误，请添加必需的 JSON 字段；在此示例中为 title。
如需了解是否需要 JSON 字段，请参阅 Cards v2 参考文档。在此示例中，请参阅 CardHeader 上的 title 字段的说明。
以下是两个示例：
示例 1：指定 subtitle 但省略必需的 title 会导致整个标头显示空白：
title，因此未显示此卡片的标题。查看错误的卡片 JSON 代码段
错误：header中缺少必填字段“title”。
. . .
"header": {
"subtitle": "Software Engineer"
}
. . .
查看正确的卡片 JSON 代码段
已修复：必填字段 title 是 header 规范的一部分。
. . .
"header": {
"title": "Sasha",
"subtitle": "Software Engineer"
}
. . .
示例 2：指定 subtitle、imageUrl、imageType 和 imageAltText 但省略必需的 title 会导致图片按预期呈现，但副标题无法呈现：
title，此卡片的标题未显示副标题，但图片可按预期呈现。查看错误的卡片 JSON 代码段
错误：header中缺少必填字段“title”。
. . .
"header": {
"subtitle": "Software Engineer",
"imageUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha",
}
. . .
查看正确的卡片 JSON 代码段
已修复：必填字段 title 是 header 规范的一部分。
. . .
"header": {
"title": "Sasha",
"subtitle": "Software Engineer",
"imageUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha",
}
. . .
原因：拼写错误或大写的 JSON
在此示例错误中，卡片 JSON 包含所有必填字段，但有一个字段 imageUrl 的大小写错误为 imageURL（大写 R 的大写 L），这会导致错误：它指向的图片无法呈现。
如需修正此错误及其他类似错误，请使用正确的 JSON 格式。在这种情况下，imageUrl 是正确的。如有疑问，请对照 card 参考文档检查卡 JSON。
title，此卡片的标题未显示副标题，但图片可按预期呈现。查看错误的卡片 JSON 代码段
错误：字段“imageURL”的大小写不正确。它应为 imageUrl。
. . .
"header": {
"title": "Sasha",
"subtitle": "Software Engineer",
"imageURL":
"https://developers.google.com/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha",
}
. . .
查看正确的卡片 JSON 代码段
已修复：字段 imageUrl 的大小写正确无误。
. . .
"header": {
"title": "Sasha",
"subtitle": "Software Engineer",
"imageUrl":
"https://developers.google.com/chat/images/quickstart-app-avatar.png",
"imageType": "CIRCLE",
"imageAltText": "Avatar for Sasha",
}
. . .
错误：未显示完整的卡片
有时卡片本身没有显示，可能的原因如下：
- 未正确指定
ButtonListwidget。 CardFixedFooterwidget 包含错误指定的按钮。
原因：错误地指定了 buttonList 或 cardFixedFooter
如果卡片消息或对话框包含指定不正确的 ButtonList widget 或包含错误指定按钮的 CardFixedFooter widget，则整个卡片不会显示，也不会显示在相应位置上。不正确的规范可能包括字段缺失、拼写或大写的字段，或者 JSON 结构不正确，例如缺少英文逗号、英文引号或大括号。
如需修正此错误，请对照卡片参考文档检查卡片 JSON。具体而言，请根据 ButtonList widget 指南比较所有 ButtonList widget。
示例：在 ButtonList widget 指南中，在第一个按钮中传递未完成的 onClick 操作会阻止系统呈现整张卡片。
查看错误的卡片 JSON 代码段
错误：onClick 对象没有指定字段，因此整个卡片都不会显示。
. . .
{
"buttonList": {
"buttons": [
{
"text": "Share",
"onClick": {
}
}
},
{
"text": "Edit",
"onClick": {
"action": {
"function": "goToView",
"parameters": [
{
"key": "viewType",
"value": "EDIT",
}
],
}
}
},
],
},
}
. . .
查看正确的卡片 JSON 代码段
修复了以下问题：onClick 对象现在具有 openLink 字段，因此卡片会按预期显示。
. . .
{
"buttonList": {
"buttons": [
{
"text": "Share",
"onClick": {
"openLink": {
"url": "https://example.com/share",
}
}
},
{
"text": "Edit",
"onClick": {
"action": {
"function": "goToView",
"parameters": [
{
"key": "viewType",
"value": "EDIT",
}
],
}
}
},
],
},
}
. . .
错误：对话框关闭、暂停或打不开
如果对话框意外关闭、无法加载或打不开，可能是由于卡片界面存在问题。
以下是最常见的原因：
CardFixedFooterwidget 没有primaryButton。CardFixedFooterwidget 中的某个按钮没有onClick操作，或其onClick操作指定不正确。TextInputwidget 缺少name字段。
原因：CardFixedFooter 没有 primaryButton
在包含 CardFixedFooter widget 的对话框中，必须指定一个同时包含文本和颜色的 primaryButton。如果省略 primaryButton 或设置不正确，则会阻止整个对话框显示。
如需修复此错误，请确保 CardFixedFooter widget 包含正确指定的 primaryButton。
查看错误的卡片 JSON 代码段
错误：fixedFooter 对象未指定 primaryButton 字段，导致对话框无法加载或打开。
. . .
"fixedFooter": {
"onClick": {
. . .
},
"secondaryButton": {
. . .
}
}
}
. . .
查看正确的卡片 JSON 代码段
修复了以下问题：fixedFooter 现在指定了 primaryButton 字段，因此对话框会按预期运行。
. . .
"fixedFooter": {
"primaryButton": {
"text": "Submit",
"color": {
"red": 0,
"blue": 1,
"green": 0
},
"onClick": {
. . .
},
"secondaryButton": {
. . .
}
}
}
. . .
原因：FixedFooter 中的 onClick 设置不正确
在包含 CardFixedFooter widget 的对话框中，错误指定任何按钮的 onClick 设置或省略此设置，导致对话框关闭、加载失败或无法打开。
如需修正此错误，请确保每个按钮都包含正确指定的 onClick 设置。
查看错误的卡片 JSON 代码段
错误：primaryButton 对象的 onClick 字段包含拼写错误的“parameters”数组，导致对话框无法加载或打开。
. . .
"fixedFooter": {
"primaryButton": {
"text": "Submit",
"color": {
"red": 0,
"blue": 1,
"green": 0
},
"onClick": {
"action": {
"function": "setLanguageType",
"parrammetters": [
{
"key": "languageType",
"value": "C++"
}
]
}
}
},
"secondaryButton": {
"text": "Cancel",
"onClick": {
"action": {
"function": "reset"
}
}
}
}
. . .
查看正确的卡片 JSON 代码段
修复了以下问题：primaryButton 对象的 onClick 字段包含拼写正确的“parameters”数组，因此对话框可以按预期运行。
. . .
"fixedFooter": {
"primaryButton": {
"text": "Submit",
"color": {
"red": 0,
"blue": 1,
"green": 0
},
"onClick": {
"action": {
"function": "setLanguageType",
"parameters": [
{
"key": "languageType",
"value": "C++"
}
]
}
}
},
"secondaryButton": {
"text": "Cancel",
"onClick": {
"action": {
"function": "reset"
}
}
}
}
. . .
原因：TextInput 没有 name
如果对话框包含排除 name 字段的 TextInput widget，则该对话框的行为不符合预期。它可能会关闭、打开，但无法加载或打不开。
如需修正此错误，请确保每个 TextInput widget 都包含适当的 name 字段。请确保卡片中的每个 name 字段都是唯一的。
查看错误的卡片 JSON 代码段
错误：textInput 对象未指定 name 字段，导致对话框关闭、加载失败或无法打开。
. . .
{
"textInput": {
"label": "Name",
"type": "SINGLE_LINE",
}
}
. . .
查看正确的卡片 JSON 代码段
修复了以下问题：textInput 现在指定了 name 字段，因此对话框会按预期运行。
. . .
{
"textInput": {
"label": "Name",
"type": "SINGLE_LINE",
"name": "contactName"
}
}
. . .
如果使用异步应用架构，对话框打开、提交或取消操作会失败
如果您的 Chat 应用在处理对话框时返回错误消息 Could not load dialog. Invalid response returned by bot.，可能是因为您的应用使用了异步架构，如 Cloud Pub/Sub 或 Create Message API 方法。
打开、提交或取消对话框需要 Chat 应用通过 DialogEventType 进行同步响应。因此，使用异步架构构建的应用不支持对话框。
如需解决此问题，请考虑使用卡片消息，而不是对话框。
其他卡片和对话框错误
如果本页介绍的修复程序无法解决您的应用遇到的与卡片相关的错误，请查询应用的错误日志。查询日志有助于查找卡片 JSON 或应用代码中的错误，并且日志包含描述性错误消息，可帮助您修复这些错误。
相关主题
如需修复 Google Chat 应用错误方面的帮助，请参阅排查并修正 Google Chat 应用问题以及调试 Chat 应用。