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

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

ในกรณีส่วนใหญ่ คุณสามารถกำหนดการดำเนินการของส่วนเสริมได้โดยใช้ 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

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

ออบเจ็กต์เหตุการณ์การกระทํา

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

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

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