عیب یابی و رفع کارت ها و دیالوگ ها

این راهنما خطاهای رایج مربوط به کارت را که ممکن است با آنها مواجه شوید و نحوه رفع آنها را شرح می‌دهد.

از Card Builder برای طراحی و پیش‌نمایش پیام‌رسانی و رابط‌های کاربری برای برنامه‌های چت استفاده کنید:

سازنده کارت را باز کنید

نحوه نمایش خطاهای کارت

خطاهای کارت به چندین روش آشکار می‌شوند:

  • بخشی از یک کارت، مانند یک ویجت یا کامپوننت، نمایش داده نمی‌شود یا به شکلی غیرمنتظره رندر می‌شود.
  • کل کارت نمایش داده نمی‌شود.
  • یک پنجره گفتگو بسته می‌شود، باز نمی‌شود، یا بارگیری نمی‌شود.

اگر با چنین رفتاری مواجه شدید، به این معنی است که خطایی در کارت برنامه شما وجود دارد.

برای مرجع: یک پیام و کادر محاوره‌ای کارت که کار می‌کند و بدون خطا است

قبل از بررسی نمونه‌های کارت‌های خطادار، ابتدا این پیام و کادر محاوره‌ای کارت فعال را در نظر بگیرید. برای نشان دادن هر خطای مثالی و رفع آن، JSON این کارت با معرفی خطاها اصلاح شده است.

پیام کارت بدون خطا

در اینجا پیام کارتی کارآمد و بدون خطا را مشاهده می‌کنید که جزئیات اطلاعات تماس را با سربرگ، بخش‌ها و ویجت‌هایی مانند متن و دکمه‌های تزئین‌شده ارائه می‌دهد:

دیالوگی بدون خطا

این پنجره‌ی محاوره‌ایِ کارآمد و بدون خطا است که با جمع‌آوری اطلاعات از کاربران، یک مخاطب ایجاد می‌کند و شامل یک پاورقی و ابزارک‌های قابل ویرایش مانند ورودی متن و سوئیچ‌ها و دکمه‌ها می‌شود:

خطا: بخشی از کارت نمایش داده نمی‌شود

گاهی اوقات کارت‌ها رندر می‌شوند، اما بخشی از کارت که انتظار داشتید ببینید، نمایش داده نمی‌شود؛ دلایل احتمالی عبارتند از:

  • یک فیلد JSON الزامی وجود ندارد.
  • یک فیلد JSON غلط املایی دارد یا به طور نادرست با حروف بزرگ نوشته شده است.
علت: فقدان یک فیلد JSON الزامی

در این مثال خطا، یک فیلد JSON الزامی، title ، وجود ندارد. در نتیجه، کارت نمایش داده می‌شود، اما بخش‌هایی از کارت که انتظار می‌رود نمایش داده شوند، نمایش داده نمی‌شوند. پیش‌بینی نحوه نمایش کارت‌ها در صورت حذف فیلدهای الزامی می‌تواند دشوار باشد.

برای رفع این خطا، فیلد JSON مورد نیاز را اضافه کنید؛ در این مثال، title .

برای اطلاع از اینکه آیا فیلد JSON مورد نیاز است یا خیر، به مستندات مرجع Cards v2 مراجعه کنید. در این مثال، به توضیحات فیلد title در CardHeader مراجعه کنید.

در اینجا دو مثال آورده شده است:

مثال ۱: مشخص کردن subtitle اما حذف title مورد نیاز باعث می‌شود کل هدر خالی ظاهر شود:
سربرگ این کارت نمایش داده نمی‌شود زیرا فیلد الزامی، عنوان، وجود ندارد.
شکل ۱ : سربرگ این کارت نمایش داده نمی‌شود زیرا فیلد الزامی، title ، وجود ندارد.
مشاهده قطعه کد JSON مربوط به کارت اشتباه

خطا: فیلد الزامی، title ، در header وجود ندارد.

    . . .
    "header": {

            "subtitle": "Software Engineer"
          }
    . . .
مشاهده قطعه کد JSON صحیح کارت

رفع شد: فیلد الزامی، title ، بخشی از مشخصات header است.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer"
          }
    . . .
مثال ۲: مشخص کردن subtitle ، imageUrl ، imageType و imageAltText اما حذف title مورد نیاز باعث می‌شود تصویر مطابق انتظار رندر شود، اما زیرنویس نه:
سربرگ این کارت نمایش داده نمی‌شود زیرا فیلد الزامی، عنوان، وجود ندارد.
شکل ۲ : سربرگ این کارت زیرنویس را نمایش نمی‌دهد زیرا فیلد الزامی title وجود ندارد، اما تصویر مطابق انتظار رندر می‌شود.
مشاهده قطعه کد JSON مربوط به کارت اشتباه

خطا: فیلد الزامی، title ، در header وجود ندارد.

    . . .
    "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 وجود ندارد، اما تصویر مطابق انتظار رندر می‌شود.
مشاهده قطعه کد 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": {
        . . .
        }
      }
    }
    . . .
علت: تنظیم نادرست onClick در FixedFooter

در دیالوگ‌هایی با ویجت 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 کارت

رفع شد: اکنون فیلد name textInput مشخص شده است، بنابراین کادر محاوره‌ای مطابق انتظار کار می‌کند. 

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",
        "name": "contactName"
      }
    }
    . . .
عملکردهای باز کردن، ارسال یا لغو دیالوگ با معماری برنامه ناهمزمان با شکست مواجه می‌شوند.

اگر برنامه چت شما هنگام کار با دیالوگ‌ها ، پیام خطای Could not load dialog. Invalid response returned by bot. ، ممکن است به این دلیل باشد که برنامه شما از معماری ناهمزمان، مانند Cloud Pub/Sub یا متد Create Message API استفاده می‌کند.

باز کردن، ارسال یا لغو یک کادر محاوره‌ای نیازمند پاسخی همزمان از یک برنامه‌ی چت با DialogEventType است. بر این اساس، کادرهای محاوره‌ای توسط برنامه‌هایی که با معماری ناهمزمان ساخته شده‌اند، پشتیبانی نمی‌شوند.

به عنوان یک راه حل، استفاده از یک پیام کارتی به جای دیالوگ را در نظر بگیرید.

سایر خطاهای کارت و کادر محاوره‌ای

اگر راه‌حل‌های شرح داده شده در این صفحه، خطای مربوط به کارت را که در برنامه شما رخ داده است، حل نکرد، گزارش‌های خطای برنامه را بررسی کنید . بررسی گزارش‌ها می‌تواند به یافتن خطاها در JSON کارت یا کد برنامه کمک کند و گزارش‌ها شامل پیام‌های خطای توصیفی هستند که به شما در رفع آنها کمک می‌کنند.

مباحث مرتبط

برای کمک به رفع خطاهای برنامه Google Chat، به عیب‌یابی و رفع مشکل برنامه Google Chat و اشکال‌زدایی برنامه‌های Chat مراجعه کنید.