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

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

يمكنك تصميم البطاقات ومعاينتها باستخدام أداة إنشاء البطاقات.

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

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

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

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

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

قبل فحص أمثلة البطاقات الخاطئة، ضع في اعتبارك أولاً رسالة بطاقة العمل هذه ومربع الحوار. لتوضيح كل مثال على خطأ وكيفية إصلاحه، يتم تعديل 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 أو طريقة Create Message API.

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

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

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

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

مواضيع ذات صلة

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