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

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

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

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

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

ฟังก์ชันเครื่องจัดการวิดเจ็ต

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

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

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

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

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

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

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

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

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