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

Ngoài việc trình bày dữ liệu, hầu hết các tiện ích bổ sung đề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 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 các thao tác vào tiện ích

Phần lớn, bạn tạo 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 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 các thao tác 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 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 trình 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 đặt 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() bằng 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 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 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 ít nhất một phương thức trình 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 xác định đối tượng Action và hàm gọi lại. Nếu trước tiên bạn cần tạo URL 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() thay thế.

  • 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 một đối tượng OpenLink để xác định URL cần mở. Bạn cũng có thể dùng đối tượng này để chỉ định hành vi mở và đóng bằng cách sử dụng các enum OpenAs và OnClose.

  • Có thể có nhiều tiện ích 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 gọi lại.

  • Giữ cho các hàm gọi lại của bạn đơn giản. Để giữ cho các tiện ích bổ sung phản hồi, Dịch vụ thẻ giới hạn các hàm gọi lại ở 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 đúng cách màn hình thẻ để phản hồi Action .

  • Nếu trạng thái dữ liệu trên một 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ì tiện ích bổ sung nên đặt một bit "đã thay đổi trạng thái" thành true để mọi bộ nhớ đệm hiện có phía máy khách đều bị xoá. Hãy xem nội dung mô tả phương thức ActionResponseBuilder.setStateChanged() để biết thêm thông tin chi tiết.