การดำเนินการของส่วนเสริมช่วยให้วิดเจ็ตมีลักษณะการทำงานแบบอินเทอร์แอกทีฟ การสร้างการดำเนินการช่วยให้คุณกำหนดสิ่งที่จะเกิดขึ้นเมื่อผู้ใช้เลือกหรืออัปเดตวิดเจ็ต
ในกรณีส่วนใหญ่ คุณจะกำหนดการดำเนินการของส่วนเสริมได้โดยใช้ออบเจ็กต์ Action
ที่บริการการ์ดของ Apps Script มีให้
Action
แต่ละรายการจะเชื่อมโยงกับฟังก์ชันเรียกกลับเมื่อคุณสร้างฟังก์ชันดังกล่าว คุณสามารถใช้ฟังก์ชันเรียกกลับ
เพื่อดำเนินขั้นตอนที่ต้องการเมื่อผู้ใช้โต้ตอบกับวิดเจ็ต นอกจากนี้ คุณต้องลิงก์ Action
กับวิดเจ็ตโดยใช้ฟังก์ชันเครื่องจัดการวิดเจ็ตที่เหมาะสมซึ่งกำหนดประเภทการโต้ตอบที่จะทริกเกอร์การติดต่อกลับของ Action
กำหนดค่าวิดเจ็ตด้วย Action
โดยใช้ขั้นตอนทั่วไปต่อไปนี้
- สร้างออบเจ็กต์
Action
โดยระบุฟังก์ชันเรียกกลับที่ควรใช้ควบคู่กับพารามิเตอร์ที่ต้องการ - เรียกฟังก์ชันเครื่องจัดการวิดเจ็ตที่เหมาะสม
ในวิดเจ็ตโดยใช้ออบเจ็กต์
Action
- ใช้ฟังก์ชันเรียกกลับเพื่อสร้างลักษณะการทำงานที่จำเป็น
ฟังก์ชันเครื่องจัดการวิดเจ็ต
หากต้องการลิงก์วิดเจ็ตกับ Action
ที่เฉพาะเจาะจงหรือลักษณะการทำงานอื่นๆ ให้ใช้ฟังก์ชันแฮนเดิลวิดเจ็ต ฟังก์ชันเครื่องจัดการจะเป็นตัวกำหนดประเภทของการโต้ตอบ (เช่น การคลิกวิดเจ็ตหรือแก้ไขช่องข้อความ) ที่จะทริกเกอร์ลักษณะการดำเนินการ ฟังก์ชันเครื่องจัดการยังระบุขั้นตอนที่ UI ทำ (หากมี) หลังจากการดำเนินการเสร็จสิ้น
ตารางต่อไปนี้แสดงรายการเครื่องจัดการประเภทต่างๆ สำหรับวิดเจ็ตและวิดเจ็ตที่ใช้กับวิดเจ็ตนั้นๆ
ฟังก์ชันเครื่องจัดการ | ทริกเกอร์การดำเนินการ | วิดเจ็ตที่เกี่ยวข้อง | คำอธิบาย |
---|---|---|---|
setOnChangeAction() |
ค่าวิดเจ็ตมีการเปลี่ยนแปลง |
DatePicker DateTimePicker SelectionInput Switch TextInput
TimePicker
|
ตั้งค่า Action ที่เรียกใช้ฟังก์ชัน Apps Script เมื่อวิดเจ็ตไม่โฟกัส เช่น เมื่อผู้ใช้ป้อนข้อความในอินพุตและกด Enter ตัวแฮนเดิลจะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันที่เรียกใช้โดยอัตโนมัติ
คุณแทรกข้อมูลพารามิเตอร์เพิ่มเติมในออบเจ็กต์เหตุการณ์นี้ได้หากต้องการ |
setOnClickAction() |
ผู้ใช้คลิกวิดเจ็ต |
CardAction Image ImageButton DecoratedText TextButton
|
ตั้งค่า Action ที่เรียกใช้ฟังก์ชัน Apps Script เมื่อผู้ใช้คลิกวิดเจ็ต ตัวแฮนเดิลจะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันที่เรียกใช้โดยอัตโนมัติ
คุณสามารถแทรกข้อมูลพารามิเตอร์ที่ไม่บังคับในออบเจ็กต์เหตุการณ์นี้ได้ |
setComposeAction() |
ผู้ใช้คลิกวิดเจ็ต |
CardAction Image ImageButton DecoratedText TextButton
|
เฉพาะ Gmail ตั้งค่า Action ที่สร้างอีเมลฉบับร่าง จากนั้นแสดงฉบับร่างดังกล่าวแก่ผู้ใช้ในหน้าต่างการเขียน UI ของ Gmail คุณสร้างข้อความร่างเป็นข้อความใหม่หรือตอบกลับข้อความที่เปิดอยู่ใน Gmail ได้ เมื่อเครื่องจัดการเรียกใช้ฟังก์ชันเรียกกลับของแบบร่างการสร้าง ตัวแฮนเดิลจะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันเรียกกลับ
ดูรายละเอียดเพิ่มเติมได้ที่เขียนข้อความร่าง |
setOnClickOpenLinkAction() |
ผู้ใช้คลิกวิดเจ็ต |
CardAction Image ImageButton DecoratedText TextButton
|
ตั้งค่า Action
ให้เปิด URL เมื่อผู้ใช้คลิกวิดเจ็ต ใช้เครื่องจัดการนี้เมื่อต้องสร้าง URL หรือต้องดำเนินการอื่นๆ ก่อนที่ลิงก์จะเปิด มิเช่นนั้นโดยทั่วไปจะใช้ setOpenLink() ได้ง่ายกว่า
คุณเปิด URL ได้เฉพาะในหน้าต่างใหม่เท่านั้น เมื่อปิดแล้ว อาจทำให้ UI โหลดส่วนเสริมซ้ำได้ |
setOpenLink() |
ผู้ใช้คลิกวิดเจ็ต |
CardAction Image ImageButton DecoratedText TextButton
|
เปิด URL โดยตรงเมื่อผู้ใช้คลิกวิดเจ็ต ใช้เครื่องจัดการนี้เมื่อคุณทราบ URL และจำเป็นต้องเปิดเท่านั้น มิเช่นนั้น ให้ใช้ setOnClickOpenLinkAction()
คุณสามารถเปิด URL ในหน้าต่างใหม่หรือในโฆษณาซ้อนทับ เมื่อปิดแล้ว อาจทำให้ UI โหลดส่วนเสริมซ้ำได้ |
setSuggestionsAction() |
ผู้ใช้ป้อนข้อความลงในอินพุต |
TextInput
|
ตั้งค่า Action ที่เรียกใช้ฟังก์ชัน Apps Script เมื่อผู้ใช้ป้อนข้อความในวิดเจ็ตอินพุตข้อความ เครื่องจัดการจะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันที่เรียกใช้โดยอัตโนมัติ
ดูรายละเอียดเพิ่มเติมได้ที่คำแนะนำที่เติมข้อความอัตโนมัติสำหรับการป้อนข้อความ |
ฟังก์ชันเรียกกลับ
ฟังก์ชันเรียกกลับจะทำงานเมื่อ Action
ทริกเกอร์ เนื่องจากฟังก์ชันเรียกกลับเป็นฟังก์ชันของ Apps Script คุณจึงเลือกให้ฟังก์ชันเหล่านี้ทำเกือบทุกอย่างที่ฟังก์ชันสคริปต์อื่นๆ ทำได้
บางครั้งฟังก์ชันเรียกกลับจะแสดงผลออบเจ็กต์การตอบกลับที่เฉพาะเจาะจง ประเภทการตอบกลับเหล่านี้จะระบุการดำเนินการเพิ่มเติมที่จำเป็นหลังจากการเรียกใช้กลับเสร็จสิ้น เช่น การแสดงการ์ดใหม่หรือการแสดงคำแนะนำที่เติมข้อความอัตโนมัติ เมื่อฟังก์ชันเรียกกลับต้องส่งออบเจ็กต์การตอบกลับที่เฉพาะเจาะจง ให้ใช้คลาสเครื่องมือสร้างในบริการการ์ดเพื่อสร้างออบเจ็กต์ดังกล่าว
ตารางต่อไปนี้แสดงเมื่อฟังก์ชันเรียกกลับต้องส่งออบเจ็กต์การตอบกลับที่เจาะจงสำหรับการดำเนินการที่เจาะจง การดำเนินการเหล่านี้ไม่เกี่ยวข้องกับแอปพลิเคชันโฮสต์เฉพาะที่ส่วนเสริมกำลังขยายอยู่
พยายามดำเนินการแล้ว | ฟังก์ชันเรียกกลับควรจะแสดงผล |
---|---|
ไปยังการ์ดต่างๆ | ActionResponse |
แสดงไอคอน Notification |
ActionResponse |
เปิดลิงก์โดยใช้ setOnClickOpenLinkAction() |
ActionResponse |
แสดงคำแนะนำที่เติมข้อความอัตโนมัติ | SuggestionResponse |
ใช้การดำเนินการแบบสากล | UniversalActionResponse |
การดำเนินการอื่นๆ | ไม่มี |
นอกจากการดำเนินการเหล่านี้แล้ว แอปพลิเคชันโฮสต์แต่ละรายการยังมีชุดการดำเนินการของตนเองซึ่งทำได้ในโฮสต์นั้นเท่านั้น โปรดดูรายละเอียดในคำแนะนำต่อไปนี้
ออบเจ็กต์เหตุการณ์การกระทำ
เมื่อส่วนเสริมทริกเกอร์ Action
UI จะสร้างออบเจ็กต์เหตุการณ์ JSON โดยอัตโนมัติและส่งต่อเป็นอาร์กิวเมนต์ไปยังฟังก์ชันเรียกกลับของ Action
ออบเจ็กต์เหตุการณ์นี้ประกอบด้วยข้อมูลเกี่ยวกับบริบทฝั่งไคลเอ็นต์ปัจจุบันของผู้ใช้ เช่น ค่าปัจจุบันของวิดเจ็ตแบบอินเทอร์แอกทีฟทั้งหมดในการ์ดที่แสดง
ออบเจ็กต์เหตุการณ์การดำเนินการมีโครงสร้าง JSON เฉพาะที่จัดระเบียบข้อมูลที่มีอยู่ในออบเจ็กต์ดังกล่าว ระบบจะใช้โครงสร้างเดียวกันนี้เมื่อทริกเกอร์หน้าแรกเริ่มทำงานเพื่อสร้างหน้าแรก หรือเมื่อทริกเกอร์ตามบริบทเริ่มทำงานเพื่ออัปเดตจอแสดงผลส่วนเสริม
ดูออบเจ็กต์เหตุการณ์เพื่อดูคำอธิบายโครงสร้างออบเจ็กต์เหตุการณ์อย่างละเอียด