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

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

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

ฟังก์ชัน Callback

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

คำเตือน: บริการการ์ดของ Apps Script จำกัดฟังก์ชันเรียกกลับให้มีเวลาดำเนินการสูงสุด 30 วินาที หากการดำเนินการใช้เวลานานกว่านั้น UI ของส่วนเสริมอาจไม่อัปเดตการแสดงการ์ดอย่างถูกต้องเพื่อตอบสนองต่อ Action

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

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

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

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

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

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

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

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

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

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

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

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

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