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 của bạn. Khi tạo 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, các mục trong trình đơn trên thanh công cụ hoặc cá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 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 tạo các tiện ích mang tính tương tác bằng cách liên kết các tiện ích đó với các thao tác cụ thể và triển khai hành vi bắt buộc trong lệnh 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 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ẽ được thực thi, cùng với bất kỳ các tham số bắt buộc.
  2. Liên kết tiện ích với Action bằng cách gọi phương thức phù hợp hàm trình xử lý tiện ích.
  3. Triển khai hàm callback để thực hiện hành vi được yêu cầu.

Ví dụ:

Ví dụ sau đây đặt một nút hiển thị thông báo người dùng sau khi nhấp vào. Lượt nhấp này sẽ kích hoạt hàm callback notifyUser() có một đối số chỉ định văn bản thông báo. Trả về một phiên bản đã dựng ActionResponse 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.

  • Sử dụng tiện ích setOpenLink() khi bạn có URL và chỉ muốn mở URL đó trong tab. Điều này giúp bạn không cần phải xác định Đối tượng Action và lệnh gọi lại . Nếu bạn cần tạo URL trước hoặc thực hiện bất kỳ thao tá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 setOpenLink() hoặc setOnClickOpenLinkAction() chức năng xử lý tiện ích, bạn cần cung cấp một OpenLink để xác định URL nào 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 OpenAs và Enum OnClose.

  • Có thể có nhiều tiện ích sử dụng cùng một tiện ích Đối tượng Action. Tuy nhiên, bạn cần xác định Đối tượng Action nếu bạn 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. Để duy trì khả năng thích ứng của tiện ích bổ sung, Dịch vụ thẻ giới hạn các hàm callback trong tối đa 30 giây thời gian thực thi. 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 màn hình thẻ đúng cách 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, bạn nên thiết lập tiện ích bổ sung "tiểu bang đã thay đổi" bit sang true để mọi bộ nhớ đệm phía máy khách hiện có đã xóa. Xem ActionResponseBuilder.setStateChanged() mô tả phương thức để biết thêm chi tiết.