นอกเหนือจากการนำเสนอข้อมูลแล้ว ส่วนเสริมส่วนใหญ่ยังกำหนดให้ผู้ใช้ป้อนข้อมูลด้วย เมื่อสร้างส่วนเสริมแบบการ์ด คุณจะใช้วิดเจ็ตแบบอินเทอร์แอกทีฟได้ เช่น ปุ่ม รายการในเมนูของแถบเครื่องมือ หรือช่องทำเครื่องหมายเพื่อขอข้อมูลที่จำเป็นสำหรับส่วนเสริมหรือให้ส่วนควบคุมการโต้ตอบอื่นๆ จากผู้ใช้
การเพิ่มการดำเนินการลงในวิดเจ็ต
โดยส่วนใหญ่ คุณจะทำให้วิดเจ็ตเป็นแบบอินเทอร์แอกทีฟได้ด้วยการลิงก์กับการดำเนินการที่เจาะจงและใช้ลักษณะการทำงานที่จำเป็นในฟังก์ชันเรียกกลับ ดูรายละเอียดที่การดำเนินการของส่วนเสริม
ในกรณีส่วนใหญ่ คุณอาจทำตามขั้นตอนทั่วไปนี้เพื่อกำหนดค่าวิดเจ็ตให้ดำเนินการอย่างใดอย่างหนึ่งเมื่อมีการเลือกหรืออัปเดต
- สร้างออบเจ็กต์
Action
โดยระบุฟังก์ชันเรียกกลับที่ควรดำเนินการ รวมถึงพารามิเตอร์ที่จําเป็น - ลิงก์วิดเจ็ตกับ
Action
โดยเรียกใช้ฟังก์ชันเครื่องจัดการวิดเจ็ตที่เหมาะสม - ใช้ฟังก์ชันเรียกกลับเพื่อสร้างลักษณะการทำงานที่จำเป็น
ตัวอย่าง
ตัวอย่างต่อไปนี้กำหนดปุ่มที่แสดงการแจ้งเตือนผู้ใช้หลังจากที่คลิก การคลิกจะทริกเกอร์ฟังก์ชันเรียกกลับ notifyUser()
ด้วยอาร์กิวเมนต์ที่ระบุข้อความแจ้งเตือน การแสดง ActionResponse
ที่สร้างขึ้นจะแสดงการแจ้งเตือนที่แสดงอยู่
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification()
.setText(notificationText)
.setType(CardService.NotificationType.INFO))
.build(); // Don't forget to build the response!
}
ออกแบบการโต้ตอบที่มีประสิทธิภาพ
เมื่อออกแบบการ์ดแบบอินเทอร์แอกทีฟ โปรดคำนึงถึงสิ่งต่อไปนี้
โดยปกติแล้ววิดเจ็ตแบบอินเทอร์แอกทีฟต้องมีเมธอดเครื่องจัดการอย่างน้อย 1 วิธีเพื่อกำหนดลักษณะการทำงาน
ใช้ฟังก์ชันแฮนเดิลวิดเจ็ต
setOpenLink()
เมื่อมี URL และต้องการเปิดในแท็บ ซึ่งจะช่วยให้ไม่จำเป็นต้องกำหนดออบเจ็กต์Action
และฟังก์ชันเรียกกลับ หากต้องการสร้าง URL ก่อนหรือทำตามขั้นตอนเพิ่มเติมก่อนเปิด URL ให้กำหนดAction
และใช้setOnClickOpenLinkAction()
แทนเมื่อใช้ฟังก์ชันเครื่องจัดการวิดเจ็ต
setOpenLink()
หรือsetOnClickOpenLinkAction()
ต้องระบุออบเจ็กต์OpenLink
เพื่อกำหนด URL ที่จะเปิด คุณยังใช้ออบเจ็กต์นี้เพื่อระบุลักษณะการเปิดและปิดโดยใช้ Enum ของOpenAs
และOnClose
ได้ด้วยวิดเจ็ตมากกว่า 1 รายการอาจใช้ออบเจ็กต์
Action
เดียวกัน อย่างไรก็ตาม คุณต้องกำหนดออบเจ็กต์Action
ที่แตกต่างกันหากต้องการระบุพารามิเตอร์ที่ต่างกันสำหรับฟังก์ชันเรียกกลับทำให้ฟังก์ชันเรียกกลับเรียบง่ายเข้าไว้ บริการการ์ดจะจำกัดฟังก์ชันเรียกกลับไว้ที่เวลาการดำเนินการสูงสุด 30 วินาทีเพื่อให้ส่วนเสริมตอบสนองได้อยู่เสมอ หากการดำเนินการใช้เวลานานกว่านั้น UI ของส่วนเสริมอาจไม่อัปเดตการแสดงการ์ดอย่างถูกต้องเพื่อตอบสนองต่อ
Action
หากสถานะข้อมูลในแบ็กเอนด์ของบุคคลที่สามมีการเปลี่ยนแปลงอันเป็นผลมาจากการโต้ตอบของผู้ใช้กับ UI ของส่วนเสริม ขอแนะนำให้ส่วนเสริมตั้งค่าบิต "เปลี่ยนสถานะ" เป็น
true
เพื่อล้างแคชฝั่งไคลเอ็นต์ที่มีอยู่ ดูรายละเอียดเพิ่มเติมได้ในคำอธิบายเมธอดActionResponseBuilder.setStateChanged()