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