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

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

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

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

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

1. สร้างออบเจ็กต์ Action โดยระบุฟังก์ชัน Callback ที่ควรเรียกใช้ พร้อมกับพารามิเตอร์ที่จําเป็น
2. ลิงก์วิดเจ็ตกับ Action โดยการเรียกใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ตที่เหมาะสม
3. ใช้ฟังก์ชัน 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 และฟังก์ชันการเรียกกลับ หากต้องสร้าง URL ก่อน หรือต้องทําขั้นตอนอื่นๆ เพิ่มเติมก่อนเปิด URL ให้กําหนด Action และใช้ setOnClickOpenLinkAction() แทน

• เมื่อใช้ฟังก์ชันตัวแฮนเดิลวิดเจ็ต setOpenLink() หรือ setOnClickOpenLinkAction() คุณจะต้องระบุออบเจ็กต์ OpenLink เพื่อกำหนด URL ที่เปิด นอกจากนี้ คุณยังใช้ออบเจ็กต์นี้เพื่อระบุลักษณะการทํางานของการเปิดและปิดโดยใช้ลิสต์OpenAs และOnClose ได้ด้วย

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

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

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