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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    . . .
    "header": {

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

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

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

    . . .
    "header": {

            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .
    

    . . .
    "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 مقابل المستند المرجعي للبطاقة.

    . . .
    "header": {
      "title": "Sasha",
      "subtitle": "Software Engineer",
      "imageURL":
      "https://developers.google.com/chat/images/quickstart-app-avatar.png",
      "imageType": "CIRCLE",
      "imageAltText": "Avatar for Sasha",
    }
    . . .
    

    . . .
    "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 بشكل غير صحيح

إذا تضمّنت رسالة بطاقة أو مربّع حوار أداة ButtonList تم تحديدها بشكل غير صحيح أو تطبيق CardFixedFooter المصغّر يتضمّن أزرارًا محدّدة بشكل غير صحيح، لن تظهر البطاقة بأكملها ولن يظهر أي شيء في مكانها. قد تتضمن المواصفات غير الصحيحة حقولاً مفقودة، أو حقول مكتوبة بحروف كبيرة أو مكتوبة بشكلٍ غير صحيح، أو محتوى JSON منظم بشكل غير صحيح، مثل عدم وجود فاصلة أو علامة اقتباس أو قوس معقوف.

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

مثال: في دليل تطبيقات ButtonList، يؤدي ضبط إجراء onClick غير مكتمل في الزر الأول إلى منع عرض البطاقة بأكملها.

    . . .
    {
      "buttonList": {
        "buttons": [
          {
            "text": "Share",
            "onClick": {


              }
            }
          },
          {
            "text": "Edit",
            "onClick": {
              "action": {
                "function": "goToView",
                "parameters": [
                  {
                    "key": "viewType",
                    "value": "EDIT",
                  }
                ],
              }
            }
          },
        ],
      },
    }
    . . .
    

    . . .
    {
      "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 المصغّر على إجراء onClick أو تم تحديد إجراء onClick الخاص به بشكل غير صحيح.
• يفتقد تطبيق TextInput المصغّر حقل name.

السبب: ليس لدى CardFixedFooter أي primaryButton

في مربعات الحوار التي تتضمن أداة CardFixedFooter، يجب تحديد primaryButton بكل من النص واللون. ويؤدي إغفال علامة primaryButton أو ضبطها بشكل غير صحيح إلى منع ظهور مربّع الحوار بالكامل.

لإصلاح هذا الخطأ، تأكَّد من أنّ التطبيق المصغّر "CardFixedFooter" يتضمّن primaryButton محدّد بشكلٍ صحيح.

    . . .
    "fixedFooter": {

        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .
    

    . . .
    "fixedFooter": {
      "primaryButton": {
        "text": "Submit",
        "color": {
          "red": 0,
          "blue": 1,
          "green": 0
        },
        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .
    

السبب: إعداد onClick غير صحيح في FixedFooter

في مربعات الحوار التي تحتوي على أداة CardFixedFooter، يتم تحديد إعداد onClick على أي زر بشكل غير صحيح أو إغفاله، ما يؤدي إلى إغلاق مربّع الحوار أو تعذُّر تحميله أو عدم فتحه.

لإصلاح هذا الخطأ، تأكَّد من أنّ كل زر يتضمّن إعداد 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"
          }
        }
      }
    }
    . . .
    

    . . .
    "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 في البطاقة فريدًا.

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",

      }
    }
    . . .
    

    . . .
    {
      "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.