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

Ngoài việc cho thấ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 trên 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ế độ điều khiển tương tác khác.

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

Đối với hầu hết trường hợp, bạn sẽ 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. Xem các hành động bổ sung để biết thông tin chi tiết.

Trong hầu hết trường hợp, bạn có thể làm theo quy trình chung sau đây để định cấu hình 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 sẽ 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ề kết quả 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ế 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 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 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 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 callback các tham số khác nhau.

  • Giữ cho các hàm callback của bạn đơn giản. Để đảm bảo tính năng thích ứng của tiện ích bổ sung, 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, có thể giao diện người dùng tiện ích bổ sung của bạn 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, 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.