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

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

使用卡片构建器设计和预览聊天应用的 JSON 卡片消息：

打开卡片制作工具

信息卡错误的显示方式

银行卡错误会以以下几种方式显现：

  • 卡片的某些部分（如微件或组件）没有以非预期方式显示或呈现。
  • 系统不会显示整个卡片。
  • 对话框关闭、无法打开或无法加载。

如果您遇到这类行为，则表示应用的卡片存在问题。

参考信息：可正常运行且不会出错的卡片消息和对话框

在查看错误的卡片示例之前，请先考虑下面的有效卡片消息和对话框。为了说明每个示例错误及其修正方法，我们在此卡片的 JSON 中引入了错误，从而进行了修改。

无错误的卡片消息

这是一张有效的无错误卡片消息，其中详细说明了 具有标题、部分和小部件（如装饰文本和按钮）：

无错误对话框

以下是一个正常运行的无错误对话框，该对话框通过收集 提供页脚和文本输入等可编辑的微件 和按钮：

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

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

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

原因：缺少必填的 JSON 字段

此示例错误中缺少必需的 JSON 字段 title。因此，卡片会呈现，但是应显示的卡片部分却没有显示。如果省略必填字段，很难预测卡片的呈现效果。

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

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

以下是两个示例：

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

<ph type="x-smartling-placeholder">
</ph> 此卡片的标题未显示，因为缺少必填字段“标题”。
图 1：由于缺少必填字段“title”，此卡片的标题未显示。

查看错误的卡片 JSON 代码段

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

    . . .
    "header": {

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

查看正确的卡片 JSON 代码段

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

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

示例 2：指定 subtitle、imageUrl、imageType 和 imageAltText 但省略必需的 title 会导致图片按预期渲染，而不是副标题：

<ph type="x-smartling-placeholder">
</ph> 此卡片的标题未显示，因为缺少必填字段“标题”。
图 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。

<ph type="x-smartling-placeholder">
</ph> 此卡片的标题未显示，因为缺少必填字段“标题”。
图 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 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 微件的对话框中，错误地为任何按钮指定 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 方法。

打开、提交或取消对话框需要以下操作： 使用 DialogEventType。 因此，应用也不支持对话框 使用异步架构构建而成。

如需解决此问题，请考虑使用 卡片消息，而不是对话框。

其他卡片和对话框错误

如果本页介绍的解决方法未能解决您的应用遇到的与卡片相关的错误，请查询应用的错误日志。查询日志有助于查找卡片 JSON 或应用代码中的错误，并且日志中包含描述性错误消息，可帮助您修正相应错误。

如需有关修复 Google Chat 应用错误的帮助，请参阅排查并修复 Google Chat 应用以及调试 Chat 应用。