排查卡片和对话框问题并加以解决

本指南介绍了您可能会遇到的常见卡片相关错误以及相应的解决方法。

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

打开卡片制作工具

卡片错误的显示方式

卡片错误会以多种方式表现出来：

  • 卡片的某个部分（例如 widget 或组件）未按预期显示或呈现。
  • 系统未显示整个卡片。
  • 对话框关闭、无法打开或无法加载。

如果您遇到此类行为，则表示应用的卡片存在错误。

参考：正常显示且无错误的卡片消息和对话框

在查看错误卡片示例之前，请先考虑以下正常显示的卡片消息和对话框。为了说明每个示例错误及其修复方法，我们在该卡片的 JSON 中引入了错误。

无错误的卡片消息

下面是包含标题、部分和微件（例如带有装饰文字和按钮的微件）的详细联系信息卡片消息，该消息已通过验证，没有任何错误：

无错误的对话框

下面是一个无错误且正常运行的对话框，它通过从用户收集信息来创建联系人，并包含页脚和可修改的 widget（例如文本输入框、开关和按钮）：

错误：卡片的部分内容未显示

有时，卡片会呈现，但您预计会看到的卡片部分却未显示；可能的原因如下：

  • 缺少必填 JSON 字段。
  • JSON 字段拼写有误或大小写不正确。

原因：缺少必需的 JSON 字段

在此示例错误中，缺少必填 JSON 字段 title。因此，卡片会呈现，但预期显示的卡片部分不会显示。如果省略必填字段，很难预测卡片的呈现方式。

如需修正此错误，请添加所需的 JSON 字段；在此示例中，为 title。

如需了解 JSON 字段是否必需，请参阅 Cards v2 参考文档。在此示例中，请参阅 CardHeader 上的 title 字段的说明。

以下是两个示例：

示例 1：指定 subtitle 但省略必需的 title 会导致整个标头显示为空白：

此卡片的标题未显示，因为缺少必填字段“标题”。
图 1：此卡片的标题未显示，因为缺少必填字段 title。

查看错误的卡片 JSON 代码段

错误：header 中缺少必填字段 title。

    . . .
    "header": {

            "subtitle": "Software Engineer"
          }
    . . .

查看正确的卡片 JSON 代码段

已修复：必填字段 title 是 header 规范的一部分。

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer"
          }
    . . .

示例 2：指定 subtitle、imageUrl、imageType 和 imageAltText，但省略必需的 title 会导致图片按预期呈现，但字幕不会：

此卡片的标题未显示，因为缺少必填字段“标题”。
图 2：此卡片的标题未显示副标题，因为缺少必填字段 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 正确无误。如有疑问，请对照卡片参考文档检查卡片 JSON。

此卡片的标题未显示，因为缺少必填字段“标题”。
图 3：此卡片的标题未显示副标题，因为缺少必填字段 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 或 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 没有 primaryButton

在包含 CardFixedFooter widget 的对话框中，必须指定同时包含文本和颜色的 primaryButton。如果省略 primaryButton 或将其设置不正确，则会导致整个对话框都不会显示。

如需修正此错误，请确保 CardFixedFooter 微件包含正确指定的 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 微件的对话框中，如果错误地为任何按钮指定 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 应用。