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, đều 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, chẳng hạn như nút, mục trong trình đơn trê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ế độ kiểm soát 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 làm cho các tiện ích có tính tương tác bằng cách liên kết chúng với các thao tác cụ thể và triển khai hành vi bắt buộc trong hàm gọi lại. Xem các hành động của tiện ích 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 này để định cấu hình một tiện ích nhằm thực hiện một thao tác 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 callback cần 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 trình xử lý tiện ích thích hợp.
  3. Triển khai hàm callback để thực thi hành vi bắt buộc.

Ví dụ:

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

  /**
   * 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ế các lượt 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 ít nhất một phương thức trình xử lý để xác định hành vi của chúng.

  • Hãy sử dụng hàm xử lý tiện ích setOpenLink() khi bạn có URL và chỉ muốn mở URL đó trong một thẻ. Điều này giúp tránh nhu cầu 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 thêm bất kỳ bước 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 các tham số khác nhau cho hàm callback.

  • Giữ cho hàm callback của bạn đơn giản. Để đảm bảo các tiện ích bổ sung có khả năng thích ứng, Dịch vụ thẻ sẽ giới hạn các hàm callback trong thời gian thực thi tối đa là 30 giây. Nếu quá trình thực thi mất nhiều thời gian hơn thế, thì 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 hiển thị thẻ theo 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 tiện ích bổ sung của bạn, thì tiện ích bổ sung nên thiết lập 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ả về phương thức ActionResponseBuilder.setStateChanged() để biết thêm thông tin chi tiết.