یک کارت یا گفتگوی تعاملی طراحی کنید

این صفحه نحوه افزودن ویجت‌ها و عناصر رابط کاربری را به پیام‌های کارت یا گفتگو توضیح می‌دهد تا کاربران بتوانند با برنامه چت Google شما تعامل داشته باشند، مانند کلیک کردن روی یک دکمه یا ارسال اطلاعات.

---

از Card Builder برای طراحی و پیش نمایش پیام های کارت JSON برای برنامه های Chat استفاده کنید:

کارت ساز را باز کنید

---

پیش نیازها

یک حساب Google Workspace با دسترسی به Google Chat .

یک برنامه چت منتشر شده. برای ایجاد یک برنامه چت، این شروع سریع را دنبال کنید.

یک دکمه اضافه کنید

ویجت ButtonList مجموعه ای از دکمه ها را نمایش می دهد. دکمه ها می توانند متن، نماد یا هر دو متن و نماد را نمایش دهند. هر Button از یک عمل OnClick پشتیبانی می کند که با کلیک کاربران روی دکمه انجام می شود. مثلا:

• با OpenLink یک لینک باز کنید تا اطلاعات بیشتری را در اختیار کاربران قرار دهید.
• action را اجرا کنید که یک تابع سفارشی را اجرا می کند، مانند فراخوانی یک API.

برای دسترسی، دکمه ها از متن جایگزین پشتیبانی می کنند.

دکمه ای اضافه کنید که یک عملکرد سفارشی را اجرا می کند

کارت زیر شامل یک ویجت ButtonList با دو دکمه است. یک دکمه اسناد توسعه دهنده Google Chat را در یک برگه جدید باز می کند. دکمه دیگر یک تابع سفارشی به نام goToView() را اجرا می کند و پارامتر viewType="BIRD EYE VIEW" را ارسال می کند.

یک دکمه با رنگ سفارشی و یک دکمه غیرفعال اضافه کنید

با تنظیم "disabled": "true" می توانید از کلیک کردن روی دکمه توسط کاربران جلوگیری کنید.

در شکل زیر کارتی متشکل از ویجت ButtonList با دو دکمه نمایش داده می شود. یک دکمه از قسمت Color برای سفارشی کردن رنگ پس‌زمینه دکمه استفاده می‌کند. دکمه دیگر با فیلد Disabled غیرفعال می شود که از کلیک کاربر روی دکمه و اجرای عملکرد جلوگیری می کند.

یک دکمه با نماد اضافه کنید

در شکل زیر کارتی متشکل از ویجت ButtonList با دو ویجت آیکون Button نمایش داده می شود. یک دکمه از قسمت knownIcon برای نمایش نماد ایمیل داخلی Google Chat استفاده می کند. دکمه دیگر از قسمت iconUrl برای نمایش یک ویجت نماد سفارشی استفاده می کند.

یک دکمه با نماد و متن اضافه کنید

در شکل زیر کارتی متشکل از ویجت ButtonList نمایش داده می شود که از کاربر می خواهد یک ایمیل ارسال کند. دکمه اول یک نماد ایمیل و دکمه دوم متن را نمایش می دهد. کاربر می تواند روی نماد یا دکمه متن کلیک کند تا عملکرد sendEmail را اجرا کند.

عناصر UI قابل انتخاب را اضافه کنید

ویجت SelectionInput مجموعه ای از موارد قابل انتخاب مانند چک باکس ها، دکمه های رادیویی، سوئیچ ها یا یک منوی کشویی را ارائه می دهد. شما می توانید از این ویجت برای جمع آوری داده های تعریف شده و استاندارد شده از کاربران استفاده کنید. برای جمع آوری داده های تعریف نشده از کاربران، به جای آن از ویجت TextInput استفاده کنید.

ویجت SelectionInput از پیشنهادهایی پشتیبانی می‌کند که به کاربران کمک می‌کند داده‌های یکنواخت را وارد کنند، و اقدامات on-change، که Actions هستند که زمانی که تغییری در یک قسمت ورودی انتخاب رخ می‌دهد، مانند انتخاب یا عدم انتخاب یک مورد توسط کاربر، اجرا می‌شوند.

برنامه های چت می توانند مقدار موارد انتخاب شده را دریافت و پردازش کنند. برای جزئیات کار با ورودی های فرم، به دریافت داده های فرم مراجعه کنید.

این بخش نمونه هایی از کارت هایی را ارائه می دهد که از ویجت SelectionInput استفاده می کنند. نمونه ها از انواع مختلفی از ورودی های بخش استفاده می کنند:

• چک باکس ها
• دکمه های رادیویی
• سوئیچ ها
• فهرست کشویی
• منوی چند انتخابی

یک چک باکس اضافه کنید

در زیر یک گفتگو نمایش داده می شود که از کاربر می خواهد با ویجت SelectionInput که از چک باکس ها استفاده می کند، مشخص کند که یک مخاطب حرفه ای، شخصی یا هر دو است:

یک دکمه رادیویی اضافه کنید

در زیر یک گفتگو نمایش داده می شود که از کاربر می خواهد با ویجت SelectionInput که از دکمه های رادیویی استفاده می کند، حرفه ای یا شخصی بودن مخاطب را مشخص کند:

یک سوئیچ اضافه کنید

در زیر یک گفتگو نمایش داده می شود که از کاربر می خواهد با ویجت SelectionInput که از سوئیچ ها استفاده می کند، مشخص کند که یک مخاطب حرفه ای، شخصی یا هر دو است:

یک منوی کشویی اضافه کنید

در زیر یک گفتگو نمایش داده می شود که از کاربر می خواهد با ویجت SelectionInput که از یک منوی کشویی استفاده می کند، حرفه ای یا شخصی بودن مخاطب را مشخص کند:

یک منوی چند انتخابی اضافه کنید

در زیر یک گفتگو نمایش داده می شود که از کاربر می خواهد مخاطبین را از منوی چند انتخابی انتخاب کند:

از منابع داده برای منوهای چند انتخابی استفاده کنید

بخش زیر نحوه استفاده از منوهای چند انتخابی برای پر کردن داده‌ها از منابع پویا، مانند برنامه Google Workspace یا منبع داده خارجی را توضیح می‌دهد.

منابع داده از Google Workspace

می توانید موارد را برای یک منوی چند انتخابی از منابع داده زیر در Google Workspace پر کنید:

• کاربران Google Workspace : فقط می‌توانید کاربران را در همان سازمان Google Workspace پر کنید.
• فضاهای گپ : کاربری که موارد را در منوی انتخاب چندگانه وارد می کند، فقط می تواند فضاهایی را که در سازمان 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"
    }
  }
}

کد زیر یک منوی چند انتخابی از فضاهای چت را نشان می دهد. برای پر کردن فضاها، ورودی انتخاب قسمت hostAppDataSource را مشخص می کند. منوی multiselect نیز 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 برای منوی پرجمعیت شهرهای ایالات متحده کند، برنامه چت شما می‌تواند قبل از اینکه کاربر تایپ کردن را تمام کند Atlanta به طور خودکار پیشنهاد دهد. می توانید تا 100 مورد را به صورت خودکار تکمیل کنید.

برای تکمیل خودکار موارد، تابعی ایجاد می کنید که منبع داده خارجی را پرس و جو می کند و هر زمان که کاربر در منوی انتخاب چندگانه تایپ می کند موارد را برمی گرداند. تابع باید موارد زیر را انجام دهد:

• یک شی رویداد را ارسال کنید که نشان دهنده تعامل کاربر با منو است.
• مشخص کنید که مقدار invokedFunction رویداد تعامل با تابع از قسمت externalDataSource مطابقت دارد.
• هنگامی که توابع مطابقت دارند، موارد پیشنهادی را از منبع داده خارجی برگردانید. برای پیشنهاد موارد بر اساس نوع نوع کاربر، مقدار کلید autocomplete_widget_query را دریافت کنید. این مقدار نشان دهنده آن چیزی است که کاربر در منو تایپ می کند.

کد زیر موارد را از یک منبع داده خارجی تکمیل می کند. با استفاده از مثال قبلی، برنامه Chat مواردی را بر اساس زمانی که عملکرد getContacts فعال می شود، پیشنهاد می کند:

اسکریپت برنامه ها

apps-script/selection-input/on-widget-update.gs

در GitHub مشاهده کنید

/**
 * 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

در GitHub مشاهده کنید

/**
 * 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 UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامه‌های گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکال‌زدایی و رفع خطاها، به عیب‌یابی و رفع خطاهای Google Chat مراجعه کنید.

مطالب مرتبط

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• ویجت DateTimePicker