تحديد وحلّ المشاكل في البطاقات ومربّعات الحوار

يصف هذا الدليل الأخطاء الشائعة التي قد تواجهها البطاقة وكيفية إصلاحها.

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقات JSON ومعاينتها لتطبيقات Chat:

فتح "أداة إنشاء البطاقات"

كيفية ظهور أخطاء البطاقات

تظهر أخطاء البطاقة بعدة طرق:

  • لا يظهر جزء من بطاقة، مثل تطبيق مصغّر أو مكوّن، أو يتم عرضه بطريقة غير متوقعة.
  • عدم ظهور البطاقة بأكملها
  • يتم إغلاق مربّع حوار أو لا يفتح أو يتعذّر تحميله.

وإذا واجهك سلوكًا من هذا القبيل، يعني ذلك أنّ ثمة خطأ في بطاقة تطبيقك.

كمرجع لك: رسالة ومربّع حوار بطاقة تعمل بدون أخطاء

قبل فحص أمثلة البطاقات الخاطئة، ضع في اعتبارك أولاً رسالة بطاقة العمل ومربع الحوار هذه. لتوضيح كل مثال على خطأ وإصلاحه، يتم تعديل ملف JSON لهذه البطاقة من خلال إدخال الأخطاء.

رسالة بطاقة خالية من الأخطاء

إليك رسالة البطاقة الصالحة الخالية من الأخطاء التي تشرح معلومات الاتصال تحتوي على عنوان وأقسام وأدوات، مثل النصوص والأزرار المزخرفة:

مربع حوار خالٍ من الأخطاء

إليك مربع الحوار الذي يعمل وخالي من الأخطاء وينشئ جهة اتصال عن طريق جمع معلومات من المستخدمين، مع عرض تذييل وأدوات قابلة للتعديل مثل إدخال النص ومفاتيح التبديل والأزرار:

خطأ: عدم ظهور جزء من البطاقة

في بعض الأحيان، يتم عرض البطاقات، ولكن لا يظهر جزء من البطاقة التي كنت تتوقع رؤيته. الأسباب المحتملة هي:

  • لم يتم إدخال حقل JSON مطلوب.
  • خطأ إملائي في حقل JSON أو مكتوب بشكلٍ غير صحيح.

السبب: عدم توفُّر حقل JSON مطلوب

في نموذج الخطأ هذا، لا يتوفّر حقل JSON مطلوب، وهو title. ونتيجةً لذلك، يتم عرض البطاقة، ولكن لا تظهر أجزاء منها يُتوقع ظهورها. قد يكون من الصعب توقُّع كيفية عرض البطاقات عند حذف الحقول المطلوبة.

لإصلاح هذا الخطأ، أضِف حقل JSON المطلوب. في هذا المثال، title.

لمعرفة ما إذا كان حقل JSON مطلوبًا أم لا، يمكنك الاطّلاع على المستندات المرجعية للإصدار 2 من البطاقات. في هذا المثال، يمكنك الرجوع إلى وصف الحقل title في CardHeader.

وإليك مثالان:

المثال 1: يؤدي تحديد السمة subtitle مع حذف السمة title المطلوبة إلى ظهور العنوان فارغًا بالكامل:

لا يتم عرض عنوان هذه البطاقة بسبب عدم وجود حقل مطلوب، وهو العنوان.
الشكل 1: لا يتم عرض عنوان هذه البطاقة بسبب عدم توفّر حقل مطلوب، وهو title.

عرض مقتطف JSON للبطاقة غير صحيح

خطأ: هناك حقل مطلوب، title، غير متوفّر في header.

    . . .
    "header": {

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

عرض مقتطف JSON الصحيح للبطاقة

ثابت: الحقل المطلوب، title، جزء من مواصفات header.

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

المثال 2: تحديد subtitle وimageUrl وimageType وimageAltText مع حذف title المطلوبة يؤدي إلى عرض الصورة على النحو المتوقّع، ولكن ليس العنوان الفرعي:

لا يتم عرض عنوان هذه البطاقة بسبب عدم وجود حقل مطلوب، وهو العنوان.
الشكل 2: لا يعرض عنوان هذه البطاقة العنوان الفرعي لأنّ هناك حقل مطلوب، وهو 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 مقابل المستند المرجعي للبطاقة.

لا يتم عرض عنوان هذه البطاقة بسبب عدم وجود حقل مطلوب، وهو العنوان.
الشكل 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 للبطاقة غير صحيح

خطأ: لم يتم تحديد حقل primaryButton في الكائن fixedFooter، ما يؤدي إلى تعذُّر تحميل مربّع الحوار أو فتحه.

    . . .
    "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 يحتوي على خطأ إملائي في مصفوفة "المَعلمات"، ما يؤدي إلى تعذُّر تحميل مربّع الحوار أو فتحه.

    . . .
    "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 مع مصفوفة "المَعلمات" مكتوبة بشكلٍ صحيح، وبالتالي يعمل مربّع الحوار على النحو المتوقّع.

    . . .
    "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 للبطاقة غير صحيح

خطأ: لم يتم تحديد حقل name في الكائن textInput، ما يؤدي إلى إغلاق مربّع الحوار أو تعذُّر تحميله أو تعذُّر فتحه.

    . . .
    {
      "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 أو يمكنك إنشاء طريقة واجهة برمجة التطبيقات Message.

يتطلب فتح مربع حوار أو إرساله أو إلغائه استجابة متزامنة من تطبيق Chat مع DialogEventType وبالتالي، لا تتوافق التطبيقات مع مربّعات الحوار باستخدام بنية غير متزامنة.

كحل بديل، يمكنك استخدام رسالة بطاقة بدلاً من مربع حوار.

الأخطاء الأخرى في البطاقات ومربّعات الحوار

إذا لم تنجح الإصلاحات الموضّحة في هذه الصفحة في حلّ الخطأ المرتبط بالبطاقة الذي يواجهه تطبيقك، يمكنك إجراء طلب بحث في سجلّات أخطاء التطبيق. يمكن أن يساعد طلب البحث في السجلات في العثور على الأخطاء في بطاقة JSON أو رمز التطبيق، وتتضمّن السجلات رسائل خطأ وصفية لمساعدتك في إصلاحها.

للمساعدة في إصلاح أخطاء تطبيقات Google Chat، يُرجى الاطّلاع على تحديد مشاكل تطبيق Google Chat وحلّها وتصحيح أخطاء التطبيقات في Chat.