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

本指南介绍了您可能会遇到的与卡片相关的常见错误，以及如何修复这些错误。

您可以使用卡片构建器为 Chat 应用设计消息传递和界面，并预览这些内容：

打开卡片构建器

卡片错误的显示方式

卡片错误有多种显示方式：

  • 卡片的一部分（例如小部件或组件）不显示或以意外方式呈现。
  • 整个卡片不显示。
  • 对话框关闭、未打开或未加载。

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

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

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

无错误的卡片消息

以下是正常运行且无错误的卡片消息，其中详细介绍了联系信息，并包含标题、部分和小部件（例如带样式的文本和按钮）：

无错误的对话框

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

错误：卡片的一部分不显示

有时卡片会呈现，但您期望看到的部分卡片不显示；可能的原因如下：

  • 缺少必需的 JSON 字段。
  • JSON 字段拼写错误或大小写错误。

原因：缺少必需的 JSON 字段

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

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

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

以下是两个示例：

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

此卡片的标题未显示，因为缺少必需的字段“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 会导致图片按预期呈现，但副标题不会呈现：

此卡片的标题未显示，因为缺少必需的字段“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。

此卡片的标题未显示，因为缺少必需的字段“title”。
图 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 小部件，或者包含按钮指定方式不正确的 CardFixedFooter 小部件，则整个卡片都不会显示，并且不会显示任何内容来替代它。指定方式不正确可能包括缺少字段、字段拼写或大小写错误，或者 JSON 结构不正确，例如缺少逗号、引号或大括号。

如需修复此错误，请对照卡片参考文档检查卡片 JSON。特别是，将任何 ButtonList 小部件与 ButtonList 小部件指南 进行比较。

示例： 在 ButtonList 小部件指南中，在第一个按钮中传递不完整的 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 小部件，必须指定同时包含文本和颜色的 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

如果对话框包含 TextInput 小部件，该小部件排除 name 字段，则对话框的行为将不符合预期。它可能会关闭、打开但无法加载，或者未打开。

如需修复此错误，请确保每个 TextInput 小部件都包含适当的 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 应用。