Tạo thẻ tương tác

Hầu hết các tiện ích bổ sung, ngoài việc trình bày dữ liệu, còn yêu cầu người dùng nhập thông tin. Khi tạo một tiện ích bổ sung dựa trên thẻ, bạn có thể sử dụng các tiện ích tương tác như nút, mục trình đơn thanh công cụ hoặc hộp đánh dấu để yêu cầu người dùng cung cấp dữ liệu mà tiện ích bổ sung của bạn cần hoặc cung cấp các chế độ điều khiển tương tác khác.

Thêm thao tác vào tiện ích

Trong hầu hết trường hợp, bạn tạo các tiện ích tương tác bằng cách liên kết các tiện ích đó với các hành động cụ thể và triển khai hành vi bắt buộc trong một hàm gọi lại. Hãy xem phần hành động bổ sung để biết thông tin chi tiết.

Trong hầu hết các trường hợp, bạn có thể làm theo quy trình chung sau để định cấu hình tiện ích thực hiện một hành động cụ thể khi được chọn hoặc cập nhật:

  1. Tạo một đối tượng Action, chỉ định hàm gọi lại sẽ thực thi, cùng với mọi tham số bắt buộc.
  2. Liên kết tiện ích với Action bằng cách gọi hàm xử lý tiện ích thích hợp.
  3. Triển khai hàm callback để thực hiện hành vi bắt buộc.

Ví dụ:

Ví dụ sau đây thiết lập một nút hiển thị thông báo cho người dùng sau khi được nhấp vào. Lượt nhấp sẽ kích hoạt hàm gọi lại notifyUser() với một đối số chỉ định văn bản thông báo. Việc trả về một ActionResponse đã tạo sẽ dẫn đến việc hiển thị thông báo.

  /**
   * 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!
  }

Thiết kế hoạt động tương tác hiệu quả

Khi thiết kế thẻ tương tác, hãy lưu ý những điều sau:

  • Các tiện ích tương tác thường cần có ít nhất một phương thức xử lý để xác định hành vi của chúng.

  • Sử dụng hàm trình xử lý tiện ích setOpenLink() khi bạn có một URL và chỉ muốn mở URL đó trong một thẻ. Điều này giúp bạn không cần phải xác định đối tượng Action và hàm gọi lại. Nếu bạn cần tạo URL trước hoặc thực hiện bất kỳ bước bổ sung nào khác trước khi mở URL, hãy xác định Action và sử dụng setOnClickOpenLinkAction().

  • Khi sử dụng các hàm trình xử lý tiện ích setOpenLink() hoặc setOnClickOpenLinkAction(), bạn cần cung cấp đối tượng OpenLink để xác định URL cần mở. Bạn cũng có thể sử dụng đối tượng này để chỉ định hành vi mở và đóng bằng cách sử dụng enum OpenAs và OnClose.

  • Nhiều tiện ích có thể sử dụng cùng một đối tượng Action. Tuy nhiên, bạn cần xác định các đối tượng Action khác nhau nếu muốn cung cấp cho hàm gọi lại nhiều tham số.

  • Giữ cho hàm callback của bạn đơn giản. Để các tiện ích bổ sung luôn phản hồi, Dịch vụ thẻ giới hạn thời gian thực thi của các hàm gọi lại ở mức tối đa là 30 giây. Nếu quá trình thực thi mất nhiều thời gian hơn, giao diện người dùng của tiện ích bổ sung có thể không cập nhật đúng cách màn hình thẻ để phản hồi Action .

  • Nếu trạng thái dữ liệu trên phần phụ trợ của bên thứ ba thay đổi do người dùng tương tác với giao diện người dùng của tiện ích bổ sung, thì bạn nên đặt bit "trạng thái đã thay đổi" thành true để xoá mọi bộ nhớ đệm phía máy khách hiện có. Hãy xem nội dung mô tả phương thức ActionResponseBuilder.setStateChanged() để biết thêm thông tin chi tiết.