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

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

استخدِم "أداة إنشاء البطاقات" لتصميم واجهات المستخدم والمراسلة ومعاينتها لتطبيقات 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 الخاص بالبطاقة مقارنةً بالمستند المرجعي card. على وجه الخصوص، قارِن أي تطبيقات مصغّرة 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 أو طريقة واجهة برمجة التطبيقات إنشاء رسالة.

يتطلّب فتح مربع حوار أو إرساله أو إلغاؤه استجابة متزامنة من تطبيق Chat يتضمّن عنصر RenderActions (على سبيل المثال، action.navigations مع pushCard أو endNavigation). ونتيجةً لذلك، لا تتوافق مربّعات الحوار مع التطبيقات التي تم إنشاؤها باستخدام بنية غير متزامنة.

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

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

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

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

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