การดำเนินการเสริม

การดำเนินการของส่วนเสริมจะมอบลักษณะการทำงานแบบอินเทอร์แอกทีฟให้กับวิดเจ็ต การสร้างการดำเนินการจะกำหนดสิ่งที่เกิดขึ้นเมื่อผู้ใช้เลือกหรืออัปเดต วิดเจ็ต

ในกรณีส่วนใหญ่ คุณสามารถกำหนดการทำงานของส่วนเสริมได้โดยใช้ Action ออบเจ็กต์ที่บริการการ์ดของ Apps Script มีให้ Action แต่ละรายการจะเชื่อมโยงกับ ฟังก์ชันเรียกกลับเมื่อคุณสร้าง คุณใช้ฟังก์ชันเรียกกลับ เพื่อทำตามขั้นตอนที่เลือกเมื่อผู้ใช้โต้ตอบกับวิดเจ็ต นอกจากนี้ คุณยังต้อง ลิงก์ Action กับวิดเจ็ต โดยใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ตที่เหมาะสม ซึ่ง กำหนดว่าการโต้ตอบประเภทใดที่ทริกเกอร์ การเรียกกลับ Action

กำหนดค่าวิดเจ็ตด้วย Action โดยใช้กระบวนการทั่วไปต่อไปนี้

1. สร้างออบเจ็กต์ Action โดยระบุฟังก์ชันเรียกกลับที่ควร เรียกใช้พร้อมกับพารามิเตอร์ที่จำเป็น
2. เรียกใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ตที่เหมาะสม ในวิดเจ็ตโดยใช้ออบเจ็กต์ Action
3. ใช้ฟังก์ชันเรียกกลับเพื่อกำหนดลักษณะการทำงานที่ต้องการ

ฟังก์ชันตัวแฮนเดิลวิดเจ็ต

หากต้องการลิงก์วิดเจ็ตกับ 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 เมื่อแฮนเดิลเรียกฟังก์ชัน Callback สำหรับการสร้างฉบับร่าง จะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชัน Callback ดูรายละเอียดเพิ่มเติมได้ที่ เขียนข้อความฉบับร่าง
setOnClickOpenLinkAction()	ผู้ใช้คลิกวิดเจ็ต	CardAction Image ImageButton DecoratedText TextButton	ตั้งค่า Action เพื่อเปิด URL เมื่อผู้ใช้คลิกวิดเจ็ต ใช้ตัวแฮนเดิลนี้เมื่อคุณ ต้องสร้าง URL หรือต้องดำเนินการอื่นๆ ก่อนที่ลิงก์จะเปิด มิฉะนั้นโดยปกติแล้วการใช้ setOpenLink() จะง่ายกว่า คุณเปิด URL ได้ในหน้าต่างใหม่เท่านั้น เมื่อปิดแล้ว คุณสามารถทำให้ UI โหลดส่วนเสริมซ้ำได้
setOpenLink()	ผู้ใช้คลิกวิดเจ็ต	CardAction Image ImageButton DecoratedText TextButton	เปิด URL โดยตรงเมื่อผู้ใช้คลิกวิดเจ็ต ใช้ตัวแฮนเดิลนี้เมื่อทราบ URL และต้องการเปิด URL เท่านั้น หรือใช้ setOnClickOpenLinkAction() คุณสามารถเปิด URL ในหน้าต่างใหม่หรือในภาพซ้อนทับ เมื่อปิดแล้ว คุณ สามารถทำให้ UI โหลดส่วนเสริมซ้ำได้
setSuggestionsAction()	ผู้ใช้ป้อนข้อความลงในอินพุต	TextInput	กำหนด Action ซึ่งเรียกใช้ฟังก์ชัน Apps Script เมื่อผู้ใช้ป้อนข้อความลงในวิดเจ็ต การป้อนข้อความ ตัวแฮนเดิลจะส่ง ออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันที่เรียกใช้โดยอัตโนมัติ ดูรายละเอียดเพิ่มเติมได้ที่คำแนะนำในการเติมข้อความอัตโนมัติ สำหรับการป้อนข้อความ

ฟังก์ชัน Callback

ฟังก์ชัน Callback จะทำงานเมื่อ Action ทริกเกอร์ เนื่องจากฟังก์ชันเรียกกลับเป็นฟังก์ชัน Apps Script คุณจึงให้ฟังก์ชันเรียกกลับทำได้เกือบทุกอย่างที่ฟังก์ชันสคริปต์อื่นๆ ทำได้

บางครั้งฟังก์ชันเรียกกลับจะแสดงผลออบเจ็กต์การตอบกลับที่เฉพาะเจาะจง การตอบกลับประเภทนี้บ่งบอกถึงการดำเนินการเพิ่มเติมที่ต้องเกิดขึ้นหลังจากที่ การเรียกกลับดำเนินการเสร็จสิ้น เช่น การแสดงการ์ดใหม่หรือการแสดง คำแนะนำในการเติมข้อความอัตโนมัติ เมื่อฟังก์ชันเรียกกลับต้องแสดงออบเจ็กต์การตอบกลับที่เฉพาะเจาะจง คุณจะใช้คลาส Builder ในบริการการ์ด เพื่อสร้างออบเจ็กต์นั้น

ตารางต่อไปนี้แสดงเวลาที่ฟังก์ชันเรียกกลับต้องแสดงออบเจ็กต์การตอบกลับที่เฉพาะเจาะจงสำหรับการดำเนินการที่เฉพาะเจาะจง การดำเนินการเหล่านี้ทั้งหมด ไม่ขึ้นอยู่กับแอปพลิเคชันโฮสต์ที่เฉพาะเจาะจงซึ่งส่วนเสริมขยายการทำงาน

การดำเนินการที่พยายาม	ฟังก์ชัน Callback ควรแสดงผล
ไปยังการ์ดต่างๆ	ActionResponse
แสดง Notification	ActionResponse
เปิดลิงก์โดยใช้ setOnClickOpenLinkAction()	ActionResponse
แสดงคำแนะนำการเติมข้อความอัตโนมัติ	SuggestionResponse
ใช้การดำเนินการสากล	UniversalActionResponse
การดำเนินการอื่นๆ	Nothing

การดำเนินการสำหรับแอปพลิเคชันโฮสต์ของ Google Workspace

นอกเหนือจากการดำเนินการเหล่านี้แล้ว แอปพลิเคชันโฮสต์แต่ละรายการยังมีชุดการดำเนินการของตัวเอง ซึ่งทำได้ในโฮสต์นั้นๆ เท่านั้น ดูรายละเอียดได้ในคำแนะนำต่อไปนี้

• การดำเนินการในปฏิทิน
• การดำเนินการในแชท
• การดำเนินการในไดรฟ์
• การดำเนินการใน Gmail
• การดำเนินการของเอดิเตอร์

ออบเจ็กต์เหตุการณ์การดำเนินการ

เมื่อส่วนเสริมทริกเกอร์ Action UI จะสร้างออบเจ็กต์เหตุการณ์ JSON โดยอัตโนมัติและส่งเป็น อาร์กิวเมนต์ไปยังฟังก์ชันเรียกกลับ Action ออบเจ็กต์เหตุการณ์นี้มีข้อมูลเกี่ยวกับบริบทฝั่งไคลเอ็นต์ปัจจุบันของผู้ใช้ เช่น ค่าปัจจุบันของวิดเจ็ตแบบอินเทอร์แอกทีฟทั้งหมดในการ์ดที่แสดง

ออบเจ็กต์เหตุการณ์การกระทํามีโครงสร้าง JSON เฉพาะที่จัดระเบียบ ข้อมูลที่ออบเจ็กต์มี ระบบจะใช้โครงสร้างเดียวกันเมื่อทริกเกอร์หน้าแรก เริ่มทำงานเพื่อสร้างหน้าแรก หรือเมื่อทริกเกอร์ตามบริบท เริ่มทำงานเพื่ออัปเดตการแสดงผลของส่วนเสริม

ดูคำอธิบายแบบเต็มเกี่ยวกับโครงสร้างออบเจ็กต์เหตุการณ์ได้ที่ออบเจ็กต์เหตุการณ์