توضّح هذه الصفحة طريقة إضافة التطبيقات المصغّرة وعناصر واجهة المستخدم إلى رسائل البطاقات أو الحوارات حتى يتمكّن المستخدمون من التفاعل مع تطبيق Google Chat، مثلاً من خلال النقر على زر أو إرسال معلومات.
يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقة JSON ومعاينتها لتطبيقات Chat، وذلك باتّباع الخطوات التالية:
فتح أداة إنشاء البطاقاتالمتطلبات الأساسية
إضافة زر
تعرض تطبيق ButtonList
المصغّر مجموعة من الأزرار. يمكن أن تعرض الأزرار نصًا أو
أيقونة أو نصًا وأيقونة. يتيح كل Button
إجراء OnClick
يحدث عندما ينقر المستخدمون على الزر. مثال:
- افتح رابطًا تشعّبيًا مع
OpenLink
لتزويد المستخدمين بمعلومات إضافية. - شغِّل
action
التي تشغِّل وظيفة مخصّصة، مثل استدعاء واجهة برمجة تطبيقات.
لتسهيل الاستخدام، تدعم الأزرار النص البديل.
إضافة زر يشغِّل دالة مخصصة
في ما يلي بطاقة تتألّف من تطبيق ButtonList
المصغّر مع زرّين.
يفتح زر واحد مستندات مطوّري برامج Google Chat في علامة تبويب جديدة. يشغّل الزر الآخر دالة مخصّصة تُسمى goToView()
ويمرر المَعلمة viewType="BIRD EYE VIEW"
.
إضافة زر بلون مخصّص وزر غير مفعّل
يمكنك منع المستخدمين من النقر على زر عن طريق إعداد "disabled": "true"
.
في ما يلي بطاقة تتألّف من تطبيق ButtonList
المصغّر مع زرَّين. يستخدم زر واحد
الحقل Color
لتخصيص لون خلفية الزر. ويتم إيقاف الزر الآخر باستخدام الحقل Disabled
، ما يمنع المستخدم من النقر على الزر وتنفيذ الدالة.
إضافة زر مع رمز
في ما يلي بطاقة مكوّنة من تطبيق ButtonList
المصغّر مع رمزَين مصغّرَين
Button
. يستخدم زر واحد الحقل
knownIcon
لعرض رمز البريد الإلكتروني المضمَّن في Google Chat. ويستخدم الزر الآخر الحقل
iconUrl
لعرض
تطبيق مصغّر للرموز المخصّصة.
إضافة زر مع رمز ونص
في ما يلي بطاقة تتألّف من تطبيق ButtonList
المصغّر وتطلب من المستخدم إرسال رسالة إلكترونية. يعرض الزر الأول رمز بريد إلكتروني
ويعرض الزر الثاني نصًا. يمكن للمستخدم النقر إما على الرمز أو زر النص
لتشغيل دالة sendEmail
.
إضافة عناصر واجهة مستخدم قابلة للاختيار
يوفر تطبيق SelectionInput
المصغّر مجموعة من العناصر التي يمكن اختيارها، مثل مربّعات الاختيار أو أزرار الاختيار أو مفاتيح التحكّم أو القائمة المنسدلة. يمكنك استخدام هذه الأداة
لجمع بيانات محددة وموحدة من المستخدمين. لجمع بيانات غير محدّدة من المستخدمين،
استخدِم تطبيق TextInput
المصغّر بدلاً من ذلك.
تتوافق أداة SelectionInput
مع الاقتراحات التي تساعد المستخدمين على إدخال بيانات موحّدة، والإجراءات القابلة للتغيير، وهي Actions
يتم تشغيلها عند حدوث تغيير في حقل إدخال اختيار، مثل اختيار المستخدم لعنصر أو إلغاء اختياره.
يمكن لتطبيقات Chat تلقّي قيمة العناصر المحدّدة ومعالجتها. للحصول على تفاصيل عن استخدام إدخالات النموذج، يُرجى الاطّلاع على تلقّي بيانات النموذج.
يقدّم هذا القسم أمثلة على البطاقات التي تستخدم تطبيق SelectionInput
المصغّر.
تستخدم الأمثلة أنواعًا مختلفة من إدخالات القسم:
إضافة مربّع اختيار
يعرض ما يلي مربّع حوار يطلب من المستخدم تحديد ما إذا كانت جهة الاتصال مهنية أو شخصية أو كليهما، باستخدام تطبيق SelectionInput
المصغّر الذي يستخدم مربّعات الاختيار:
إضافة زر اختيار
يعرض ما يلي مربّع حوار يطلب من المستخدم تحديد ما إذا كانت جهة الاتصال مهنية أم شخصية من خلال تطبيق SelectionInput
المصغّر الذي يستخدم أزرار الاختيار:
إضافة مفتاح تحكّم
في ما يلي مربّع حوار يطلب من المستخدم تحديد ما إذا كانت جهة الاتصال مهنية أم شخصية أم كليهما باستخدام تطبيق SelectionInput
المصغّر الذي
يستخدم مفاتيح التحكّم:
إضافة قائمة منسدلة
يعرض ما يلي مربع حوار يطلب من المستخدم تحديد ما إذا كانت جهة الاتصال مهنية أم شخصية من خلال تطبيق SelectionInput
المصغّر الذي يستخدم قائمة منسدلة:
إضافة قائمة اختيار متعدّد
يعرض ما يلي مربع حوار يطلب من المستخدم تحديد جهات الاتصال من قائمة تحديد متعدد:
استخدام مصادر البيانات لقوائم متعددة الاختيارات
يوضّح القسم التالي كيفية استخدام قوائم الاختيار المتعدد لتعبئة البيانات من مصادر ديناميكية، مثل تطبيق Google Workspace أو مصدر بيانات خارجي.
مصادر البيانات من Google Workspace
يمكنك تعبئة العناصر في قائمة اختيار متعدّد من مصادر البيانات التالية في Google Workspace:
- مستخدمو Google Workspace: يمكنك تعبئة المستخدمين ضمن مؤسسة Google Workspace نفسها فقط.
- مساحات Chat: لا يمكن للمستخدم الذي يُدخل عناصر في قائمة الاختيار المتعدد الاطّلاع إلا على المساحات التي ينتمي إليها واختيارها داخل مؤسسته على Google Workspace.
لاستخدام مصادر بيانات Google Workspace، عليك تحديد الحقل
platformDataSource
. على عكس أنواع الإدخال الأخرى، يمكنك حذف عناصر
SectionItem
،
لأن عناصر الاختيار هذه يتم الحصول عليها ديناميكيًا من
Google Workspace.
يعرض الرمز التالي قائمة اختيار متعدّدة لمستخدمي Google Workspace.
لتعبئة المستخدمين، تضبط إعدادات الإدخال commonDataSource
على USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
يعرض الرمز التالي قائمة تحديد عناصر متعددة لمساحات Chat. لتعبئة المساحات، يحدّد إدخال الاختيار
الحقل hostAppDataSource
. تضبط قائمة التحديد المتعدد أيضًا
defaultToCurrentSpace
على true
، ما يجعل المساحة الحالية الاختيار
التلقائي في القائمة:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
مصادر البيانات خارج Google Workspace
يمكن أيضًا لقوائم التحديد المتعدد تعبئة العناصر من مصدر بيانات تابع لجهة خارجية أو خارجية. على سبيل المثال، يمكنك استخدام قوائم اختيار متعدد لمساعدة المستخدم على الاختيار من قائمة عملاء المبيعات المحتملين من نظام إدارة العلاقات مع العملاء (CRM).
لاستخدام مصدر بيانات خارجي، يمكنك استخدام الحقل externalDataSource
لتحديد دالة تعرض عناصر من مصدر البيانات.
لتقليل الطلبات الواردة إلى مصدر بيانات خارجي، يمكنك تضمين العناصر
المقترَحة التي تظهر في قائمة الاختيار المتعدّد قبل كتابة المستخدمين
في القائمة. على سبيل المثال، يمكنك تعبئة جهات الاتصال التي تم البحث عنها مؤخرًا للمستخدم. لتعبئة العناصر المقترَحة من مصدر بيانات خارجي، حدِّد كائنات
SelectionItem
.
يعرض الرمز التالي قائمة تحديد متعددة من العناصر من مجموعة خارجية من جهات الاتصال للمستخدم. تعرض القائمة جهة اتصال واحدة تلقائيًا
وتشغّل الدالة getContacts
لاسترداد العناصر وملئها من
مصدر البيانات الخارجي:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 2,
"externalDataSource": {
"function": "getContacts"
},
"items": [
{
"text": "Contact 3",
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"bottomText": "Contact three description",
"selected": false
}
]
}
}
بالنسبة إلى مصادر البيانات الخارجية، يمكنك أيضًا إكمال العناصر التي يبدأ المستخدمون في كتابتها في قائمة الاختيار المتعدد. على سبيل المثال، إذا بدأ أحد المستخدمين كتابة Atl
لقائمة تشغل المدن في الولايات المتحدة، يمكن لتطبيق Chat اقتراح Atlanta
تلقائيًا قبل أن ينتهي المستخدم من الكتابة. يمكنك الإكمال التلقائي لما يصل إلى 100 عنصر.
لإكمال العناصر تلقائيًا، يمكنك إنشاء دالة تستعلم عن مصدر البيانات الخارجي وتعرض العناصر كلما كتب مستخدم في قائمة التحديد المتعدد. يجب أن تقوم الدالة بما يلي:
- مرِّر كائن حدث يمثّل تفاعل المستخدِم مع القائمة.
- حدِّد أن قيمة
invokedFunction
لحدث التفاعل تتطابق مع الدالة من الحقلexternalDataSource
. - عند تطابق الدوال، يتم عرض العناصر المقترحة من مصدر البيانات الخارجي. لاقتراح عناصر استنادًا إلى أنواع المستخدمين، احصل على قيمة المفتاح
autocomplete_widget_query
. تمثل هذه القيمة ما يكتبه المستخدم في القائمة.
يؤدي الرمز التالي إلى الإكمال التلقائي للعناصر من مورد بيانات خارجي. باستخدام
المثال السابق، يقترح تطبيق Chat عناصر استنادًا إلى
عند تشغيل الدالة getContacts
:
برمجة تطبيقات
Node.js
إضافة حقل يمكن للمستخدم إدخال نص فيه
توفّر تطبيق TextInput
المصغّر
حقلاً يمكن للمستخدمين إدخال نص فيه. وتتوافق
التطبيق المصغر مع الاقتراحات التي تساعد المستخدمين على إدخال بيانات موحّدة،
والإجراءات
الأثناء التغيير، وهي
Actions
يتم تشغيلها عند حدوث تغيير في حقل إدخال النص، مثلاً عندما يضيف المستخدم نصًا أو يحذفه.
عندما تحتاج إلى جمع بيانات مختصرة أو غير معروفة من المستخدمين، استخدِم تطبيق
TextInput
المصغّر هذا. لجمع بيانات محدّدة من المستخدمين، استخدِم
تطبيق SelectionInput
المصغّر بدلاً من ذلك.
لمعالجة النص الذي يُدخله المستخدمون، راجِع تلقّي بيانات النموذج.
في ما يلي بطاقة تتألّف من تطبيق TextInput
المصغّر:
السماح للمستخدم باختيار تاريخ ووقت
تتيح
أداة DateTimePicker
للمستخدمين إدخال تاريخ أو وقت أو إدخال تاريخ ووقت معًا. أو يمكن للمستخدمين استخدام أداة الاختيار لاختيار التواريخ والأوقات. إذا أدخل المستخدمون تاريخًا أو وقتًا غير صالح، ستعرض أداة الاختيار خطأ يطلب من المستخدمين إدخال المعلومات بشكل صحيح.
لمعالجة قيم التاريخ والوقت التي يُدخلها المستخدمون، راجِع المقالة تلقّي بيانات النموذج.
في ما يلي بطاقة تتألّف من ثلاثة أنواع مختلفة من
تطبيقات DateTimePicker
المصغّرة:
تحديد المشاكل وحلّها
عندما يعرض تطبيق Google Chat أو بطاقة رسالة خطأ، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن يعرض تطبيق Chat أو البطاقة نتيجة غير متوقعة. على سبيل المثال، قد لا تظهر رسالة بطاقة.
قد لا تظهر رسالة الخطأ في واجهة مستخدم Chat، ولكن تتوفّر رسائل خطأ وصفية وبيانات السجلّ لمساعدتك في إصلاح الأخطاء عند تفعيل تسجيل الأخطاء في تطبيقات Chat. للحصول على مساعدة في عرض الأخطاء وتصحيحها وتصحيحها، يُرجى الاطّلاع على تحديد وحلّ مشاكل Google Chat.