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

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

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

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

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

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()