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

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

استخدِم "أداة إنشاء البطاقات" لتصميم واجهتَي المستخدم والرسائل ومعاينتهما في تطبيقات 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 إجراء onClick، أو تم تحديد إجراء onClick بشكل غير صحيح.
  • لا يتضمّن التطبيق المصغّر TextInput حقل name.

السبب: لا يتضمّن CardFixedFooter primaryButton

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

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

عرض مقتطف JSON الخاص بالبطاقة الذي يتضمّن خطأ

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

    . . .
    "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 الخاص بالبطاقة الذي يتضمّن خطأ

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

    . . .
    {
      "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 أو Create Message في واجهة برمجة التطبيقات.

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

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

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

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

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