این صفحه نحوه افزودن ویجتها و عناصر رابط کاربری را به پیامهای کارت یا گفتگو توضیح میدهد تا کاربران بتوانند با برنامه چت Google شما تعامل داشته باشند، مانند کلیک کردن روی یک دکمه یا ارسال اطلاعات.
از Card Builder برای طراحی و پیش نمایش پیام های کارت JSON برای برنامه های Chat استفاده کنید:
کارت ساز را باز کنیدپیش نیازها
یک برنامه Google Chat که برای ویژگیهای تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی، یکی از شروع سریع زیر را بر اساس معماری برنامه ای که می خواهید استفاده کنید، انجام دهید:
- سرویس HTTP با توابع Google Cloud
- اسکریپت Google Apps
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
یک دکمه اضافه کنید
ویجت ButtonList
مجموعه ای از دکمه ها را نمایش می دهد. دکمه ها می توانند متن، نماد یا هر دو متن و نماد را نمایش دهند. هر Button
از یک عمل OnClick
پشتیبانی می کند که با کلیک کاربران روی دکمه انجام می شود. به عنوان مثال:
- با
OpenLink
یک لینک باز کنید تا اطلاعات بیشتری را در اختیار کاربران قرار دهید. -
action
را اجرا کنید که یک تابع سفارشی را اجرا می کند، مانند فراخوانی یک API.
برای دسترسی، دکمه ها از متن جایگزین پشتیبانی می کنند.
دکمه ای اضافه کنید که یک عملکرد سفارشی را اجرا می کند
کارت زیر شامل یک ویجت ButtonList
با دو دکمه است. یک دکمه اسناد توسعه دهنده Google Chat را در یک برگه جدید باز می کند. دکمه دیگر یک تابع سفارشی به نام goToView()
را اجرا می کند و پارامتر viewType="BIRD EYE VIEW"
را ارسال می کند.
یک دکمه با سبک طراحی متریال اضافه کنید
در زیر مجموعه ای از دکمه ها در سبک های مختلف دکمه طراحی متریال نمایش داده می شود.
برای اعمال سبک طراحی متریال، ویژگی «color» را وارد نکنید.
یک دکمه با رنگ سفارشی و یک دکمه غیرفعال اضافه کنید
با تنظیم "disabled": "true"
می توانید از کلیک کردن روی دکمه توسط کاربران جلوگیری کنید.
در شکل زیر کارتی متشکل از ویجت ButtonList
با دو دکمه نمایش داده می شود. یک دکمه از قسمت Color
برای سفارشی کردن رنگ پسزمینه دکمه استفاده میکند. دکمه دیگر با فیلد Disabled
غیرفعال می شود که از کلیک کاربر روی دکمه و اجرای عملکرد جلوگیری می کند.
یک دکمه با نماد اضافه کنید
در شکل زیر کارتی متشکل از ویجت ButtonList
با دو ویجت آیکون Button
نمایش داده می شود. یک دکمه از قسمت knownIcon
برای نمایش نماد ایمیل داخلی Google Chat استفاده می کند. دکمه دیگر از قسمت iconUrl
برای نمایش یک ویجت نماد سفارشی استفاده می کند.
یک دکمه با نماد و متن اضافه کنید
در شکل زیر کارتی متشکل از ویجت ButtonList
نمایش داده می شود که از کاربر می خواهد یک ایمیل ارسال کند. دکمه اول یک نماد ایمیل و دکمه دوم متن را نمایش می دهد. کاربر می تواند روی نماد یا دکمه متن کلیک کند تا عملکرد sendEmail
را اجرا کند.
یک منوی سرریز اضافه کنید
Overflow menu
میتواند در کارتهای چت برای ارائه گزینهها و اقدامات اضافی استفاده شود. این به شما امکان می دهد گزینه های بیشتری را بدون درهم ریختگی رابط کارت اضافه کنید و از طراحی تمیز و سازماندهی شده اطمینان حاصل کنید.
یک لیست چیپس اضافه کنید
ویجت ChipList
روشی همه کاره و جذاب برای نمایش اطلاعات ارائه می دهد. از فهرستهای تراشهها برای نمایش برچسبها، دستهها یا سایر دادههای مرتبط استفاده کنید تا کاربران بتوانند با محتوای شما حرکت کنند و با آنها تعامل داشته باشند.
عناصر 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
فعال می شود، پیشنهاد می کند:
اسکریپت برنامه ها
Node.js
فیلدی اضافه کنید که کاربر بتواند متن را در آن وارد کند
ویجت 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
را در dateTimePicker تنظیم کنید
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 UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.
اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیامهای خطای توصیفی و دادههای گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامههای گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکالزدایی و رفع خطاها، به عیبیابی و رفع خطاهای Google Chat مراجعه کنید.