يشرح هذا الدليل الأخطاء الشائعة ذات الصلة بالبطاقات التي قد تواجهها وكيفية إصلاحها.
يمكنك تصميم البطاقات ومعاينتها باستخدام أداة إنشاء البطاقات.
فتح أداة إنشاء البطاقاتكيفية ظهور الأخطاء في البطاقات
تظهر أخطاء البطاقة بعدة طرق:
- لا يظهر جزء من بطاقة، مثل تطبيق مصغّر أو مكوِّن، أو يتم عرضه بطريقة غير متوقعة.
- عدم ظهور البطاقة بأكملها
- يتم إغلاق مربّع الحوار أو تعذّر فتحه أو لا يتم تحميله.
إذا واجهت سلوكًا كهذا، يعني ذلك أنّ هناك خطأ في بطاقة تطبيقك.
كمرجع لك: رسالة ومربّع حوار بطاقة عمل خالية من الأخطاء وخالية من الأخطاء
قبل فحص أمثلة البطاقات الخاطئة، ضع في اعتبارك أولاً رسالة بطاقة العمل هذه ومربع الحوار. لتوضيح كل مثال على خطأ وكيفية إصلاحه، يتم تعديل JSON لهذه البطاقة من خلال إدخال أخطاء.
رسالة بطاقة خالية من الأخطاء
في ما يلي رسالة بطاقة عمل خالية من الأخطاء توضح معلومات الاتصال التي تحتوي على عنوان وأقسام وتطبيقات مصغّرة مثل النصوص والأزرار المزخرفة:
مربع حوار خالٍ من الأخطاء
إليك مربع الحوار العملي والخالي من الأخطاء الذي ينشئ جهة اتصال عن طريق جمع المعلومات من المستخدمين، مع عرض تذييل وأدوات قابلة للتعديل مثل إدخال النص ومفاتيح التبديل والأزرار:
خطأ: لا يظهر جزء من بطاقة
في بعض الأحيان، يتم عرض البطاقات، ولكن لا يظهر جزء من بطاقة كنت تتوقع رؤيتها، الأسباب المحتملة هي:
- لم يتم إدخال حقل JSON مطلوب.
- يتضمّن حقل JSON خطأً إملائيًا أو تمت كتابته بشكلٍ غير صحيح.
السبب: حقل JSON المطلوب غير متوفّر
في نموذج الخطأ هذا، حقل JSON المطلوب، title
غير متوفّر. ونتيجةً لذلك، يتم عرض البطاقة، ولكن لا يتم عرض بعض أجزاء البطاقة المتوقّع ظهورها. قد يصعب توقُّع كيفية عرض البطاقات عند حذف الحقول المطلوبة.
لإصلاح هذا الخطأ، أضِف حقل JSON المطلوب، في هذا المثال، title
.
لمعرفة ما إذا كان حقل JSON مطلوبًا أم لا، يمكنك الاطّلاع على المستندات المرجعية للإصدار 2 من البطاقات. في هذا المثال، ارجع إلى وصف الحقل title
على CardHeader
.
وإليك مثالان:
المثال 1: تحديد subtitle
مع حذف title
المطلوب يؤدي إلى ظهور العنوان بالكامل فارغًا:
![لا يتم عرض عنوان هذه البطاقة بسبب عدم إدخال أحد الحقول المطلوبة، وهو العنوان.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-1.png?authuser=7&hl=ar)
title
.عرض مقتطف JSON للبطاقة غير صحيح
خطأ: هناك حقل مطلوب، title
، غير متوفّر في header
.
. . . "header": { "subtitle": "Software Engineer" } . . .
عرض مقتطف JSON الصحيح للبطاقة
ثابت: الحقل المطلوب، title
، هو جزء من مواصفات header
.
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
المثال 2: تحديد subtitle
وimageUrl
وimageType
وimageAltText
مع حذف title
المطلوب يؤدي إلى عرض الصورة على النحو المتوقع، ولكن ليس العنوان الفرعي:
![لا يتم عرض عنوان هذه البطاقة بسبب عدم إدخال أحد الحقول المطلوبة، وهو العنوان.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-2.png?authuser=7&hl=ar)
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 للبطاقة مقابل المستند المرجعي للبطاقة.
![لا يتم عرض عنوان هذه البطاقة بسبب عدم إدخال أحد الحقول المطلوبة، وهو العنوان.](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-imageURL-instead-of-imageUrl.png?authuser=7&hl=ar)
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
بشكلٍ غير صحيح
إذا تضمّنت رسالة بطاقة أو مربّع حوار يتضمّنان تطبيقًا مصغّرًا لـ 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
مع مصفوفة "parameters" مكتوبة بشكلٍ صحيح، لذا يعمل مربّع الحوار على النحو المتوقّع.
. . . "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 API.
يتطلب فتح مربع حوار أو إرساله أو إلغاؤه
استجابة متزامنة من تطبيق في Chat باستخدام
DialogEventType
.
وفقًا لذلك، لا تتوافق التطبيقات التي تم إنشاؤها باستخدام بنية غير متزامنة مع مربّعات الحوار.
كحل بديل، يمكنك استخدام رسالة بطاقة بدلاً من مربّع حوار.
أخطاء أخرى في البطاقات ومربّعات الحوار
إذا لم تساعد الإصلاحات الموضّحة في هذه الصفحة على حلّ الخطأ المرتبط بالبطاقة في تطبيقك، يمكنك طلب البحث عن سجلّات الأخطاء في التطبيق. يمكن أن يساعد طلب البحث في السجلات في العثور على الأخطاء في ملف JSON للبطاقة أو رمز التطبيق، وتتضمن السجلات رسائل خطأ وصفية لمساعدتك في إصلاحها.
مواضيع ذات صلة
للحصول على المساعدة في حلّ أخطاء تطبيقات Google Chat، يمكنك الاطّلاع على مقالة تحديد وحلّ المشاكل في تطبيق Google Chat وتصحيح أخطاء تطبيقات Chat.