การสร้างการ์ดแบบอินเทอร์แอกทีฟ

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

การเพิ่มการดำเนินการลงในวิดเจ็ต

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

ในกรณีส่วนใหญ่ คุณอาจทำตามขั้นตอนทั่วไปนี้เพื่อกำหนดค่าวิดเจ็ตให้ดำเนินการอย่างใดอย่างหนึ่งเมื่อมีการเลือกหรืออัปเดต

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

ตัวอย่าง

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