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

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

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

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

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

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

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

ฟังก์ชันเรียกกลับ

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

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

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

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

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

ออบเจ็กต์เหตุการณ์การกระทำ

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

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

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