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

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

يمكنك استخدام "أداة إنشاء البطاقات" لتصميم رسائل بطاقات JSON ومعاينتها لتطبيقات Chat:

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

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

  • حساب Google Workspace مع إمكانية الوصول إلى Google Chat
  • تطبيق Chat منشور لإنشاء تطبيق 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

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

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

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

    تشرح هذه الصفحة كيفية التحقّق من صحة البيانات التي تم إدخالها في 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 أو تعرض card خطأً، تعرض واجهة Chat رسالة مفادها "حدث خطأ". أو "تعذَّرت معالجة طلبك". في بعض الأحيان، لا يمكن واجهة مستخدم Chat لا يعرض أي رسالة خطأ، ولكن يظهر تطبيق Chat أو ينتج عن بطاقة نتيجة غير متوقعة؛ على سبيل المثال، قد لا تظهر رسالة البطاقة موضع الإعلان.

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