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

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

استخدِم أداة Card Builder لتصميم واجهات المراسلة والمستخدم ومعاينتها لتطبيقات Chat:

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

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

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

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

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

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

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

في ما يلي رسالة البطاقة الصالحة والخالية من الأخطاء التي توضّح معلومات الاتصال وتتضمّن رأسًا وأقسامًا وأدوات مثل النص المنسّق والأزرار:

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

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

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

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

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

السبب: لم يتم إدخال حقل JSON مطلوب

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

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

لمعرفة ما إذا كان حقل JSON مطلوبًا أم لا، يُرجى الاطّلاع على مستندات مرجع Cards v2. في هذا المثال، يُرجى الرجوع إلى وصف حقل 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 widget بشكلٍ غير صحيح.
• تتضمّن أداة CardFixedFooter widget زرًا تم تحديده بشكلٍ غير صحيح.

السبب: تم تحديد 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 widget حقل 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 widget، يؤدي تحديد إعداد 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. أثناء العمل مع مربّعات الحوار، قد يرجع ذلك إلى أنّ تطبيقك يستخدم بنية غير متزامنة architecture، مثل Cloud Pub/Sub أو طريقة Create Message API.

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

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

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

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

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

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