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

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

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

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

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

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

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

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

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

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

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

หมายเหตุ: เมื่อใช้คลาสเครื่องมือสร้างคำตอบ อย่าลืมเรียกใช้ build() เพื่อสร้างออบเจ็กต์คำตอบ มิเช่นนั้นระบบจะแสดงข้อผิดพลาด

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

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

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

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

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

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