ส่วนเสริมส่วนใหญ่นอกจากจะนำเสนอข้อมูลแล้ว ยังกำหนดให้ผู้ใช้ป้อนข้อมูลด้วย เมื่อสร้างส่วนเสริมแบบการ์ด คุณสามารถใช้วิดเจ็ตแบบอินเทอร์แอกทีฟ เช่น ปุ่ม รายการในเมนูในแถบเครื่องมือ หรือช่องทำเครื่องหมายเพื่อขอข้อมูลที่ส่วนเสริมจำเป็นต้องใช้ หรือมอบการควบคุมการโต้ตอบอื่นๆ จากผู้ใช้ได้
การเพิ่มการดำเนินการลงในวิดเจ็ต
คุณจะทำให้วิดเจ็ตเป็นแบบอินเทอร์แอกทีฟได้โดยลิงก์กับการดำเนินการที่เจาะจงและใช้ลักษณะการทำงานที่จำเป็นในฟังก์ชัน Callback โปรดดูรายละเอียดในการดำเนินการของส่วนเสริม
ในกรณีส่วนใหญ่ คุณสามารถทำตามขั้นตอนทั่วไปต่อไปนี้เพื่อกำหนดค่าวิดเจ็ตให้ดำเนินการเฉพาะเมื่อมีการเลือกหรืออัปเดต
- สร้างออบเจ็กต์
Action
โดยระบุฟังก์ชัน Callback ที่ควรดำเนินการ พร้อมกับพารามิเตอร์ที่จำเป็น - ลิงก์วิดเจ็ตกับ
Action
โดยเรียกใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ตที่เหมาะสม - ใช้ฟังก์ชัน Callback เพื่อทำตามลักษณะการทำงานที่จำเป็น
ตัวอย่าง
ตัวอย่างต่อไปนี้เป็นการตั้งค่าปุ่มที่จะแสดงการแจ้งเตือนสำหรับผู้ใช้หลังจากมีการคลิกปุ่มดังกล่าว การคลิกจะเป็นการทริกเกอร์ฟังก์ชัน Callback 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)
.build(); // Don't forget to build the response!
}
ออกแบบการโต้ตอบที่มีประสิทธิภาพ
เมื่อออกแบบการ์ดอินเทอร์แอกทีฟ ให้คำนึงถึงสิ่งต่อไปนี้
วิดเจ็ตแบบอินเทอร์แอกทีฟมักจะต้องใช้เมธอดเครื่องจัดการอย่างน้อย 1 วิธีเพื่อกำหนดลักษณะการทำงาน
ใช้ฟังก์ชันแฮนเดิลวิดเจ็ตของ
setOpenLink()
เมื่อคุณมี URL และต้องการเปิดในแท็บ เพื่อหลีกเลี่ยงความจำเป็นต้องกำหนดออบเจ็กต์Action
และฟังก์ชัน Callback หากจำเป็นต้องสร้าง URL ก่อนหรือทำตามขั้นตอนเพิ่มเติมอื่นๆ ก่อนเปิด URL ให้กำหนดAction
และใช้setOnClickOpenLinkAction()
แทนเมื่อใช้ฟังก์ชันเครื่องจัดการวิดเจ็ต
setOpenLink()
หรือsetOnClickOpenLinkAction()
คุณต้องระบุออบเจ็กต์OpenLink
เพื่อกำหนดว่าจะเปิด URL ใด คุณยังใช้ออบเจ็กต์นี้เพื่อระบุพฤติกรรมการเปิดและปิดโดยใช้ EnumOpenAs
และOnClose
ได้ด้วยวิดเจ็ตมากกว่า 1 รายการจะใช้ออบเจ็กต์
Action
เดียวกันได้ อย่างไรก็ตาม คุณต้องกำหนดออบเจ็กต์Action
ที่แตกต่างกันหากต้องการระบุพารามิเตอร์อื่นของฟังก์ชัน Callbackทำให้ฟังก์ชัน Callback ของคุณเรียบง่ายอยู่เสมอ บริการของการ์ดจะจำกัดฟังก์ชัน Callback ไว้สูงสุดที่ 30 วินาทีเพื่อให้ส่วนเสริมทำงานที่ปรับเปลี่ยนตามอุปกรณ์อยู่เสมอ หากการดำเนินการใช้เวลานานกว่านั้น UI ของส่วนเสริมอาจไม่อัปเดตการแสดงการ์ดอย่างถูกต้องเพื่อตอบสนองต่อ
Action
หากสถานะข้อมูลในแบ็กเอนด์ของบุคคลที่สามเปลี่ยนแปลงเนื่องจากการโต้ตอบของผู้ใช้กับ UI ของส่วนเสริม เราขอแนะนําให้ตั้งค่าบิต "เปลี่ยนสถานะ" ของส่วนเสริมเป็น
true
เพื่อล้างแคชฝั่งไคลเอ็นต์ที่มีอยู่ ดูรายละเอียดเพิ่มเติมได้จากคำอธิบายเมธอดActionResponseBuilder.setStateChanged()