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

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

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقات JSON ومعاينتها لتطبيقات 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

    يمكن لقوائم التحديد المتعدد أيضًا تعبئة العناصر من مصدر بيانات تابع لجهة خارجية أو خارجي. على سبيل المثال، يمكنك استخدام قوائم اختيار متعدد لمساعدة المستخدم على الاختيار من قائمة عملاء المبيعات المحتملين من نظام إدارة العلاقات مع العملاء.

    لاستخدام مصدر بيانات خارجي، يمكنك استخدام الحقل 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

    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 تطبيقات مصغّرة:

    التحقق من صحة البيانات التي تم إدخالها في البطاقات

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

    ضبط التطبيقات المصغّرة المطلوبة للإجراءات

    كجزء من action الخاصة بالبطاقة، أضِف أسماء التطبيقات المصغّرة التي يحتاجها الإجراء إلى قائمة requiredWidgets.

    إذا كانت أي تطبيقات مصغّرة مدرَجة هنا لا تحتوي على قيمة عند استدعاء هذا الإجراء، يتم إلغاء إرسال الإجراء على النموذج.

    عند ضبط "all_widgets_are_required": "true" على تنفيذ إجراء، حينئذٍ يكون هذا الإجراء مطلوبًا في جميع التطبيقات المصغّرة في البطاقة.

    ضبط إجراء all_widgets_are_required في ميزة الاختيار المتعدد

    JSON

    {
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "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
              }
            ]
          }
        }
      ]
    }
  ]
}

    ضبط إجراء "all_widgets_are_required" في "منتقي التاريخ والوقت"

    JSON

    {
  "sections": [
    {
      "widgets": [
        {
          "textParagraph": {
            "text": "A datetime picker widget with both date and time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_and_time",
            "label": "meeting",
            "type": "DATE_AND_TIME"
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just date:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_date_only",
            "label": "Choose a date",
            "type": "DATE_ONLY",
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textParagraph": {
            "text": "A datetime picker widget with just time:"
          }
        },
        {
          "divider": {}
        },
        {
          "dateTimePicker": {
            "name": "date_time_picker_time_only",
            "label": "Select a time",
            "type": "TIME_ONLY"
          }
        }
      ]
    }
  ]
}

    ضبط إجراء all_widgets_are_required في القائمة المنسدلة

    JSON

    {
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "all_widgets_are_required": true
            },
            "items": [
              {
                "text": "Red",
                "value": "red",
                "selected": false
              },
              {
                "text": "Green",
                "value": "green",
                "selected": false
              },
              {
                "text": "White",
                "value": "white",
                "selected": false
              },
              {
                "text": "Blue",
                "value": "blue",
                "selected": false
              },
              {
                "text": "Black",
                "value": "black",
                "selected": false
              }
            ]
          }
        }
      ]
    }
  ]
}

    ضبط التحقّق من تطبيق مصغّر لإدخال النص

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

    ضبط عدد الأحرف المسموح به لتطبيق إدخال النص

    JSON

    {
  "sections": [
    {
      "header": "Tell us about yourself",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "favoriteColor",
            "label": "Favorite color",
            "type": "SINGLE_LINE",
            "validation": {"character_limit":15},
            "onChangeAction":{
              "all_widgets_are_required": true
            }
          }
        }
      ]
    }
  ]
}

    ضبط نوع الإدخال لأداة إدخال النص

    JSON

    {
  "sections": [
    {
      "header": "Validate text inputs by input types",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 2,
      "widgets": [
        {
          "textInput": {
            "name": "mailing_address",
            "label": "Please enter a valid email address",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "EMAIL"
            },
            "onChangeAction": {
              "all_widgets_are_required": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "input_type": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "input_type": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

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

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

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