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

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

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

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

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

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

ตัวอย่าง

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

• วิดเจ็ตมากกว่า 1 รายการสามารถใช้ออบเจ็กต์ Action เดียวกันได้ อย่างไรก็ตาม คุณต้องกำหนดออบเจ็กต์ Action ที่แตกต่างกันหากต้องการระบุพารามิเตอร์ที่แตกต่างกันสำหรับฟังก์ชัน Callback

• ทำให้ฟังก์ชันเรียกกลับเรียบง่าย บริการการ์ดจะจำกัดฟังก์ชันเรียกกลับให้มีเวลาดำเนินการสูงสุด 30 วินาที เพื่อให้ส่วนเสริมตอบสนองได้ หากการดำเนินการใช้เวลานานกว่านั้น UI ของส่วนเสริมอาจ อัปเดตการแสดงการ์ดอย่างไม่ถูกต้องเพื่อตอบสนองต่อ Action

• หากสถานะข้อมูลในแบ็กเอนด์ของบุคคลที่สามเปลี่ยนแปลงอันเป็นผลมาจากการโต้ตอบของผู้ใช้กับ UI ของส่วนเสริม เราขอแนะนำให้ส่วนเสริมตั้งค่าบิต "state changed" เป็น true เพื่อให้ระบบล้างแคชฝั่งไคลเอ็นต์ที่มีอยู่ ดูรายละเอียดเพิ่มเติมได้ที่คำอธิบายเมธอด ActionResponseBuilder.setStateChanged()