يصف هذا الدليل الأخطاء الشائعة التي قد تواجهها البطاقة وكيفية إصلاحها.
يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقات JSON ومعاينتها لتطبيقات Chat:
فتح "أداة إنشاء البطاقات"كيفية ظهور أخطاء البطاقات
تظهر أخطاء البطاقة بعدة طرق:
- لا يظهر جزء من بطاقة، مثل تطبيق مصغّر أو مكوّن، أو يتم عرضه بطريقة غير متوقعة.
- عدم ظهور البطاقة بأكملها
- يتم إغلاق مربّع حوار أو لا يفتح أو يتعذّر تحميله.
وإذا واجهك سلوكًا من هذا القبيل، يعني ذلك أنّ ثمة خطأ في بطاقة تطبيقك.
كمرجع لك: رسالة ومربّع حوار بطاقة صالحة وخالية من الأخطاء
قبل فحص أمثلة البطاقات الخاطئة، ضع في اعتبارك أولاً رسالة بطاقة العمل ومربع الحوار هذه. لتوضيح كل مثال على خطأ وإصلاحه، يتم تعديل ملف 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=19&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=19&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=19&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 للبطاقة غير صحيح
خطأ: لم يتم تحديد حقل primaryButton
في الكائن fixedFooter
، ما يؤدي إلى تعذُّر تحميل مربّع الحوار أو فتحه.
. . . "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 للبطاقة غير صحيح
خطأ: لم يتم تحديد حقل name
في الكائن textInput
، ما يؤدي إلى إغلاق مربّع الحوار أو تعذُّر تحميله أو تعذُّر فتحه.
. . . { "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 أو
يمكنك إنشاء طريقة واجهة برمجة التطبيقات Message.
يتطلب فتح مربع حوار أو إرساله أو إلغائه
استجابة متزامنة من تطبيق Chat مع
DialogEventType
وبالتالي، لا تتوافق التطبيقات مع مربّعات الحوار
باستخدام بنية غير متزامنة.
كحل بديل، يمكنك استخدام رسالة بطاقة بدلاً من مربع حوار.
الأخطاء الأخرى في البطاقات ومربّعات الحوار
إذا لم تنجح الإصلاحات الموضّحة في هذه الصفحة في حلّ الخطأ المرتبط بالبطاقة الذي يواجهه تطبيقك، يمكنك إجراء طلب بحث في سجلّات أخطاء التطبيق. يمكن أن يساعد طلب البحث في السجلات في العثور على الأخطاء في بطاقة JSON أو رمز التطبيق، وتتضمّن السجلات رسائل خطأ وصفية لمساعدتك في إصلاحها.
مواضيع ذات صلة
للمساعدة في إصلاح أخطاء تطبيقات Google Chat، يُرجى الاطّلاع على تحديد مشاكل تطبيق Google Chat وحلّها وتصحيح أخطاء التطبيقات في Chat.