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

Hầu hết 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 như nút, mục trong 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ế độ kiểm soát tương tác khác.

Thêm hành động vào tiện ích

Đối với hầu hết các phần, bạn giúp các tiện ích có tính 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 hàm gọi lại. Xem các thao tác bổ sung để biết chi tiết.

Trong hầu hết trường hợp, bạn có thể làm theo quy trình chung này để định cấu hình tiện ích nhằm 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 callback sẽ thực thi cùng với mọi thông 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 gọi lại để thực hiện hành vi bắt buộc.

Ví dụ:

Ví dụ sau đây sẽ thiết lập 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 thông bá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. Thao tác trả về kết quả tích hợp ActionResponse sẽ xuất hiện trong 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)
            .setType(CardService.NotificationType.INFO))
        .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 ghi nhớ 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 xử lý để xác định hành vi của các tiện ích đó.

  • 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ẻ. Việc 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. Trước tiên, nếu bạn cần tạo URL hoặc thực hiện thêm 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 xử lý tiện ích setOpenLink() hoặc setOnClickOpenLinkAction(), bạn cần cung cấp một đố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ố cho hàm gọi lại.

  • Hãy đơn giản hoá các hàm gọi lại. Để giữ cho các tiện ích bổ sung phản hồi, Dịch vụ thẻ sẽ giới hạn các hàm gọi lại 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ì giao diện người dùng của tiện ích bổ sung có thể không cập nhật hiển thị thẻ đúng cách để 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 tương tác của người dùng với giao diện người dùng tiện ích bổ sung, bạn nên đặt tiện ích bổ sung đó thành một "trạng thái đã thay đổi" thành true để xoá bộ nhớ đệm phía máy khách hiện có. Vui lòng xem nội dung mô tả về phương thức ActionResponseBuilder.setStateChanged() để biết thêm thông tin chi tiết.