หน้านี้อธิบายวิธีเพิ่มวิดเจ็ตและองค์ประกอบ UI ลงในการ์ดหรือข้อความโต้ตอบ เพื่อให้ผู้ใช้โต้ตอบกับแอป Google Chat ได้ เช่น การคลิกปุ่มหรือส่งข้อมูล
ใช้เครื่องมือสร้างการ์ดเพื่อออกแบบและแสดงตัวอย่างข้อความการ์ด JSON สำหรับแอป Chat ดังนี้
เปิดเครื่องมือสร้างการ์ดสิ่งที่ต้องดำเนินการก่อน
เพิ่มปุ่ม
วิดเจ็ต ButtonList
จะแสดงปุ่มชุดหนึ่ง ปุ่มสามารถแสดงข้อความ ไอคอน หรือทั้งข้อความและไอคอน Button
แต่ละรายการรองรับการดำเนินการ OnClick
ที่เกิดขึ้นเมื่อผู้ใช้คลิกปุ่ม เช่น
- เปิดไฮเปอร์ลิงก์ด้วย
OpenLink
เพื่อให้ข้อมูลเพิ่มเติมแก่ผู้ใช้ - เรียกใช้
action
ที่เรียกใช้ฟังก์ชันที่กำหนดเอง เช่น การเรียก API
สำหรับการช่วยเหลือพิเศษ ปุ่มจะรองรับข้อความสำรอง
เพิ่มปุ่มที่เรียกใช้ฟังก์ชันที่กำหนดเอง
ต่อไปนี้คือการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList
ที่มี 2 ปุ่ม
ปุ่มหนึ่งจะเปิดเอกสารประกอบสําหรับนักพัฒนาซอฟต์แวร์ Google Chat ในแท็บใหม่ ปุ่มอื่นๆ จะเรียกใช้ฟังก์ชันที่กำหนดเองชื่อ goToView()
และส่งพารามิเตอร์ viewType="BIRD EYE VIEW"
เพิ่มปุ่มที่มีสีที่กําหนดเองและปุ่มที่ปิดใช้งานแล้ว
คุณป้องกันไม่ให้ผู้ใช้คลิกปุ่มได้โดยการตั้งค่า "disabled": "true"
การ์ดต่อไปนี้จะแสดงการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList
ที่มี 2 ปุ่ม ปุ่มหนึ่งจะใช้ช่อง Color
เพื่อปรับแต่งสีพื้นหลังของปุ่ม ปุ่มอีกปุ่มหนึ่งจะถูกปิดใช้งานด้วยช่อง Disabled
ซึ่งจะป้องกันไม่ให้ผู้ใช้คลิกปุ่มดังกล่าวและเรียกใช้ฟังก์ชัน
เพิ่มปุ่มที่มีไอคอน
รายการต่อไปนี้แสดงการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList
พร้อมไอคอน 2 วิดเจ็ต
Button
ปุ่มเดียวใช้ช่อง knownIcon
เพื่อแสดงไอคอนอีเมลในตัวของ Google Chat อีกปุ่มหนึ่งจะใช้ช่อง iconUrl
เพื่อแสดงวิดเจ็ตไอคอนที่กำหนดเอง
เพิ่มปุ่มที่มีไอคอนและข้อความ
การ์ดต่อไปนี้จะแสดงการ์ดที่ประกอบด้วยวิดเจ็ต ButtonList
ที่แจ้งให้ผู้ใช้ส่งอีเมล ปุ่มแรกจะแสดงไอคอนอีเมล
และปุ่มที่สองจะแสดงข้อความ ผู้ใช้จะคลิกไอคอนหรือปุ่มข้อความเพื่อเรียกใช้ฟังก์ชัน sendEmail
ได้
เพิ่มองค์ประกอบ UI ที่เลือกได้
วิดเจ็ต SelectionInput
มีชุดรายการที่เลือกได้ เช่น ช่องทำเครื่องหมาย ปุ่มตัวเลือก สวิตช์ หรือเมนูแบบเลื่อนลง คุณสามารถใช้วิดเจ็ตนี้
เพื่อรวบรวมข้อมูลที่กำหนดไว้และที่ได้มาตรฐานจากผู้ใช้ หากต้องการรวบรวมข้อมูลที่ไม่ระบุจากผู้ใช้ ให้ใช้วิดเจ็ต TextInput
แทน
วิดเจ็ต SelectionInput
รองรับคำแนะนำ ซึ่งจะช่วยให้ผู้ใช้ป้อนข้อมูลแบบเดียวกันและการดำเนินการเมื่อเปลี่ยนแปลง ซึ่งก็คือ Actions
ที่จะทำงานเมื่อมีการเปลี่ยนแปลงเกิดขึ้นในช่องป้อนข้อมูลการเลือก เช่น ผู้ใช้เลือกหรือยกเลิกการเลือกรายการ
แอปแชทจะรับและประมวลผลมูลค่าของรายการที่เลือกได้ โปรดดูรายละเอียดเกี่ยวกับการทำงานกับอินพุตแบบฟอร์มที่หัวข้อรับข้อมูลแบบฟอร์ม
ส่วนนี้จะแสดงตัวอย่างการ์ดที่ใช้วิดเจ็ต SelectionInput
ตัวอย่างใช้อินพุตส่วนประเภทต่างๆ ดังนี้
เพิ่มช่องทำเครื่องหมาย
รายการต่อไปนี้จะแสดงกล่องโต้ตอบที่ขอให้ผู้ใช้ระบุว่าผู้ติดต่อเป็นมืออาชีพ ส่วนตัว หรือทั้ง 2 อย่าง พร้อมวิดเจ็ต SelectionInput
ที่ใช้ช่องทำเครื่องหมาย
เพิ่มปุ่มตัวเลือก
รายการต่อไปนี้จะแสดงกล่องโต้ตอบที่ขอให้ผู้ใช้ระบุว่าผู้ติดต่อเป็นมืออาชีพหรือส่วนตัวด้วยวิดเจ็ต SelectionInput
ที่ใช้ปุ่มตัวเลือก
เพิ่มสวิตช์
รายการต่อไปนี้จะแสดงกล่องโต้ตอบที่ขอให้ผู้ใช้ระบุว่าผู้ติดต่อเป็นมืออาชีพ ส่วนตัว หรือทั้ง 2 อย่างด้วยวิดเจ็ต 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
โค้ดต่อไปนี้แสดงเมนูการเลือกหลายรายการจากชุดรายชื่อติดต่อภายนอกสำหรับผู้ใช้ เมนูจะแสดงรายชื่อติดต่อ 1 รายการโดยค่าเริ่มต้น และเรียกใช้ฟังก์ชัน 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
Node.js
เพิ่มช่องที่ผู้ใช้ป้อนข้อความได้
วิดเจ็ต TextInput
มีช่องที่ผู้ใช้ป้อนข้อความได้ วิดเจ็ตจะรองรับคําแนะนําซึ่งช่วยให้ผู้ใช้ป้อนข้อมูลแบบเดียวกันและการดำเนินการเปลี่ยนแปลงต่างๆ ซึ่งก็คือ Actions
ที่จะทำงานเมื่อมีการเปลี่ยนแปลงเกิดขึ้นในช่องป้อนข้อความ เช่น เมื่อผู้ใช้เพิ่มหรือลบข้อความ
ใช้วิดเจ็ต TextInput
นี้เมื่อคุณต้องการรวบรวมข้อมูลแบบนามธรรมหรือไม่ทราบจากผู้ใช้ หากต้องการรวบรวมข้อมูลที่กำหนดไว้จากผู้ใช้ ให้ใช้วิดเจ็ต SelectionInput
แทน
หากต้องการประมวลผลข้อความที่ผู้ใช้ป้อน โปรดดูรับข้อมูลในแบบฟอร์ม
ต่อไปนี้คือการ์ดที่ประกอบด้วยวิดเจ็ต TextInput
ให้ผู้ใช้เลือกวันที่และเวลา
วิดเจ็ต DateTimePicker
ช่วยให้ผู้ใช้ป้อนวันที่ เวลา หรือทั้งวันที่และเวลาได้ หรือผู้ใช้จะใช้เครื่องมือเลือกเพื่อเลือกวันที่และเวลาก็ได้ หากผู้ใช้ป้อนวันที่หรือเวลาไม่ถูกต้อง เครื่องมือเลือกจะแสดงข้อผิดพลาดที่แจ้งให้ผู้ใช้ป้อนข้อมูลอย่างถูกต้อง
หากต้องการประมวลผลค่าวันที่และเวลาที่ผู้ใช้ป้อน โปรดดูรับข้อมูลแบบฟอร์ม
การ์ดต่อไปนี้แสดงการ์ดที่ประกอบด้วยวิดเจ็ต DateTimePicker
ประเภทต่างๆ 3 ประเภท
ตรวจสอบข้อมูลที่ป้อนลงในการ์ด
หน้านี้อธิบายวิธีตรวจสอบข้อมูลที่ป้อนลงใน 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
ใน dateTime Picker
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 จะแสดงข้อความว่า "เกิดข้อผิดพลาด" หรือ "ไม่สามารถดำเนินการตามคำขอของคุณ" บางครั้ง UI ของ Chat ไม่แสดงข้อความแสดงข้อผิดพลาด แต่แอปหรือการ์ด Chat ให้ผลลัพธ์ที่ไม่คาดคิด เช่น ข้อความในการ์ดอาจไม่ปรากฏขึ้น
แม้ว่าข้อความแสดงข้อผิดพลาดอาจไม่แสดงใน UI ของ Chat แต่ก็ยังมีข้อความแสดงข้อผิดพลาดและข้อมูลบันทึกที่สื่อความหมายเพื่อช่วยให้คุณแก้ไขข้อผิดพลาดเมื่อมีการเปิดใช้การบันทึกข้อผิดพลาดสำหรับแอป Chat ได้ หากต้องการความช่วยเหลือในการดู แก้ไขข้อบกพร่อง และแก้ไขข้อผิดพลาด โปรดดูหัวข้อแก้ปัญหาและแก้ไขข้อผิดพลาดของ Google Chat