本指南介绍了您可能遇到的与卡片相关的常见错误及解决方法。
使用卡片制作工具设计和预览卡片。
打开卡片制作工具卡片错误的显示方式
卡片错误会以以下几种方式呈现:
- 卡片的某些部分(例如微件或组件)不会以非预期方式显示或呈现。
- 整张卡片也不会显示。
- 对话框关闭、无法打开或无法加载。
如果您遇到此类行为,则表示应用的卡片有误。
参考信息:有效的无错误卡片消息和对话框
在检查错误的卡片示例之前,请先考虑这张有效的卡片消息和对话框。为说明每个示例错误及其修复方法,我们通过引入错误修改了此卡片的 JSON。
无错误的卡消息
下面是有效的无错卡片消息,其中详细说明了联系信息,其中包含标题、部分以及装饰文本和按钮等 widget:
无错误的对话框
下面展示了这个无错的有效对话框,它通过向用户收集信息、显示页脚、文本输入、开关以及按钮等可编辑 widget 来创建联系人:
错误:卡片的部分内容未显示
有时,卡片会渲染,但您想看到的卡片部分却没有显示;可能的原因如下:
- 缺少必填的 JSON 字段。
- JSON 字段拼写错误或大小写错误。
原因:缺少必需的 JSON 字段
此示例错误中缺少必需的 JSON 字段 title
。因此,卡片可以呈现,但本应显示的部分却没有。如果省略必填字段,可能很难预测卡片的呈现效果。
如需修正此错误,请添加必需的 JSON 字段;在此示例中为 title
。
如需了解是否需要 JSON 字段,请参阅 Cards v2 参考文档。在此示例中,请参阅 CardHeader
上的 title
字段的说明。
以下是两个示例:
示例 1:指定 subtitle
但省略必需的 title
会导致整个标头显示空白:
![由于缺少必填字段“标题”,因此不会显示此卡片的标题。](https://developers.google.cn/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-1.png?authuser=8&hl=lv)
title
,因此未显示此卡片的标题。查看错误的卡片 JSON 代码段
错误:header
中缺少必填字段“title
”。
. . . "header": { "subtitle": "Software Engineer" } . . .
查看正确的卡片 JSON 代码段
已修复:必填字段 title
是 header
规范的一部分。
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
示例 2:指定 subtitle
、imageUrl
、imageType
和 imageAltText
但省略必需的 title
会导致图片按预期呈现,但副标题无法呈现:
![由于缺少必填字段“标题”,因此不会显示此卡片的标题。](https://developers.google.cn/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-2.png?authuser=8&hl=lv)
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。
![由于缺少必填字段“标题”,因此不会显示此卡片的标题。](https://developers.google.cn/static/workspace/chat/images/troubleshoot/troubleshoot-cards-imageURL-instead-of-imageUrl.png?authuser=8&hl=lv)
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", } . . .
错误:未显示完整的卡片
有时卡片本身没有显示,可能的原因如下:
- 未正确指定
ButtonList
widget。 CardFixedFooter
widget 包含错误指定的按钮。
原因:错误地指定了 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", } ], } } }, ], }, } . . .
错误:对话框关闭、暂停或打不开
如果对话框意外关闭、无法加载或打不开,可能是由于卡片界面存在问题。
以下是最常见的原因:
CardFixedFooter
widget 没有primaryButton
。CardFixedFooter
widget 中的某个按钮没有onClick
操作,或其onClick
操作指定不正确。TextInput
widget 缺少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 应用。