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

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

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

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

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

อย่าสับสนระหว่างออบเจ็กต์ Action กับออบเจ็กต์ CardAction CardAction ออบเจ็กต์คือรายการเมนูส่วนหัวของการ์ด ส่วนออบเจ็กต์ Action จะกำหนด การตอบสนองต่อการโต้ตอบของผู้ใช้กับ UI

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

หากต้องการลิงก์วิดเจ็ตกับ 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 คุณจึงให้ฟังก์ชันเรียกกลับทำเกือบทุกอย่างที่ฟังก์ชันสคริปต์อื่นๆ ทำได้

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

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

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

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

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

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

เมื่อใช้คลาสเครื่องมือสร้างการตอบกลับ ให้เรียกใช้เมธอด build เพื่อสร้างออบเจ็กต์การตอบกลับ การไม่ดำเนินการดังกล่าวจะทำให้เกิดข้อผิดพลาด

การดำเนินการสากลจะกำหนดไว้ ในไฟล์ Manifest ของโปรเจ็กต์และไม่จำเป็นต้องมีออบเจ็กต์ Action แต่ฟังก์ชันเรียกกลับของออบเจ็กต์ต้องส่งคืน UniversalActionResponse

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

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

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

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

ส่วนเสริม Gmail ใช้โครงสร้างออบเจ็กต์เหตุการณ์เวอร์ชันที่เรียบง่ายกว่า ซึ่งตอนนี้เลิกใช้งานแล้ว เพื่อความเข้ากันได้แบบย้อนหลัง ฟิลด์ออบเจ็กต์เหตุการณ์ของส่วนเสริม Gmail เดิมทั้งหมด จะยังคงอยู่ในโครงสร้างออบเจ็กต์เหตุการณ์ใหม่ (ดูโครงสร้างออบเจ็กต์เหตุการณ์) อย่างไรก็ตาม ระบบจะสร้างข้อมูลเดียวกันนี้ซ้ำในโครงสร้างย่อยของออบเจ็กต์ commonEventObject และกิจกรรม Gmail หากคุณอัปเกรดส่วนเสริม Gmail เป็นส่วนเสริม Google Workspace ให้อัปเดตรหัสเพื่อใช้ฟิลด์ออบเจ็กต์เหตุการณ์ที่อัปเดตแล้ว ในที่สุด ระบบจะนำฟิลด์ออบเจ็กต์กิจกรรม Gmail เดิมออก