تصميم بطاقة أو مربع حوار تفاعلي

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

يمكنك تصميم البطاقات ومعاينتها باستخدام أداة إنشاء البطاقات.

فتح أداة إنشاء البطاقات

المتطلبات الأساسية

  • حساب على Google Workspace يمكنه الوصول إلى Google Chat
  • هو تطبيق Chat منشور. لإنشاء تطبيق في Chat، اتّبِع quickstart.

    • إضافة زر

    تعرض تطبيق 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:

    برمجة تطبيقات

    apps-script/selection-input/on-widget-update.gs
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    Node.js

    node/selection-input/on-widget-update.js
    /**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

    إضافة حقل يمكن للمستخدم إدخال نص فيه

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

    عندما تحتاج إلى جمع بيانات مختصرة أو غير معروفة من المستخدمين، استخدِم تطبيق TextInput المصغّر هذا. لجمع بيانات محدّدة من المستخدمين، استخدِم تطبيق SelectionInput المصغّر بدلاً من ذلك.

    لمعالجة النص الذي يُدخله المستخدمون، راجِع تلقّي بيانات النموذج.

    في ما يلي بطاقة تتألّف من تطبيق TextInput المصغّر:

    السماح للمستخدم باختيار تاريخ ووقت

    تتيح أداة DateTimePicker للمستخدمين إدخال تاريخ أو وقت أو إدخال تاريخ ووقت معًا. أو يمكن للمستخدمين استخدام أداة الاختيار لاختيار التواريخ والأوقات. إذا أدخل المستخدمون تاريخًا أو وقتًا غير صالح، ستعرض أداة الاختيار خطأ يطلب من المستخدمين إدخال المعلومات بشكل صحيح.

    لمعالجة قيم التاريخ والوقت التي يُدخلها المستخدمون، راجِع المقالة تلقّي بيانات النموذج.

    في ما يلي بطاقة تتألّف من ثلاثة أنواع مختلفة من تطبيقات DateTimePicker المصغّرة:

    تحديد المشاكل وحلّها

    عندما يعرض أحد تطبيقات Google Chat أو بطاقة رسالة خطأ، تعرض واجهة Chat رسالة مفادها "حدث خطأ" أو "تعذّرت معالجة طلبك". في بعض الأحيان، لا تعرض واجهة مستخدم Chat أي رسالة خطأ، ولكن يعرض تطبيق Chat أو البطاقة نتيجة غير متوقعة. على سبيل المثال، قد لا تظهر رسالة بطاقة.

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