Thao tác với tiện ích bổ sung

Các hành động của tiện ích bổ sung cung cấp hành vi tương tác cho tiện ích. Bằng cách tạo một thao tác, bạn xác định điều gì sẽ xảy ra khi người dùng chọn hoặc cập nhật một tiện ích.

Trong hầu hết các trường hợp, bạn có thể xác định các hành động bổ sung bằng cách sử dụng Action các đối tượng do dịch vụ Thẻ của Apps Script cung cấp. Mỗi Action được liên kết với một hàm callback khi bạn tạo. Bạn triển khai hàm callback để thực hiện các bước mong muốn khi người dùng tương tác với tiện ích. Bạn cũng phải liên kết Action với tiện ích bằng cách sử dụng chức năng trình xử lý tiện ích thích hợp xác định loại tương tác kích hoạt Lệnh gọi lại Action.

Định cấu hình tiện ích có Action bằng quy trình chung này:

  1. Tạo đối tượng Action, chỉ định hàm callback thực thi cùng với mọi tham số cần thiết.
  2. Gọi hàm trình xử lý tiện ích thích hợp trên tiện ích bằng cách sử dụng Action .
  3. Triển khai hàm callback để thực thi hành vi bắt buộc.

Các hàm trình xử lý tiện ích

Cách liên kết một tiện ích với một Action cụ thể hoặc hành vi khác, bạn sẽ sử dụng tiện ích hàm xử lý. Hàm xử lý xác định loại tương tác (ví dụ: việc nhấp vào tiện ích hoặc chỉnh sửa một trường văn bản) sẽ kích hoạt hành động cụ thể. Hàm xử lý này cũng xác định các bước mà giao diện người dùng thực hiện, nếu có, sau khi hành động hoàn tất.

Bảng sau đây liệt kê các loại trình xử lý khác nhau cho tiện ích và những gì các tiện ích mà chúng được dùng với:

Hàm trình xử lý Kích hoạt hành động Các tiện ích có thể áp dụng Mô tả
setOnChangeAction() Giá trị của tiện ích sẽ thay đổi DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
Đặt một Action thực thi một hàm Apps Script khi tiện ích mất đi tiêu điểm, chẳng hạn như chẳng hạn như khi người dùng nhập văn bản vào một mục nhập và nhấn Enter. Chiến lược phát hành đĩa đơn trình xử lý tự động truyền event (đối tượng sự kiện) vào hàm mà nó gọi. Bạn có thể chèn thêm thông tin về thông số vào đối tượng sự kiện này nếu muốn.
setOnClickAction() Người dùng nhấp vào tiện ích CardAction
Image
ImageButton
DecoratedText
TextButton
Đặt một Action thực thi hàm Apps Script khi người dùng nhấp vào tiện ích. Chiến lược phát hành đĩa đơn trình xử lý tự động truyền event (đối tượng sự kiện) vào hàm mà nó gọi. Bạn có thể chèn thông tin không bắt buộc về thông số vào đối tượng sự kiện này.
setComposeAction() Người dùng nhấp vào tiện ích CardAction
Image
ImageButton
DecoratedText
TextButton
Dành riêng cho Gmail. Đặt một Action tạo email nháp, sau đó hiển thị email nháp đó cho người dùng trong Cửa sổ soạn thư của giao diện người dùng Gmail. Bạn có thể tạo bản nháp dưới dạng một thông báo mới hoặc trả lời thư đang mở trong Gmail. Khi trình xử lý gọi hàm hàm callback tạo bản nháp, hàm này sẽ truyền một tham số đối tượng sự kiện cho hàm callback. Xem Soạn thư nháp để biết thêm chi tiết.
setOnClickOpenLinkAction() Người dùng nhấp vào tiện ích CardAction
Image
ImageButton
DecoratedText
TextButton
Đặt một Action để mở một URL khi người dùng nhấp vào tiện ích. Sử dụng trình xử lý này khi bạn phải tạo URL hoặc các hành động khác phải diễn ra trước khi liên kết mở; nếu không thì thường đơn giản hơn là sử dụng setOpenLink(). Bạn chỉ có thể mở URL trong cửa sổ mới. Khi đóng, bạn có thể khiến Giao diện người dùng để tải lại tiện ích bổ sung.
setOpenLink() Người dùng nhấp vào tiện ích CardAction
Image
ImageButton
DecoratedText
TextButton
Mở trực tiếp một URL khi người dùng nhấp vào tiện ích. Sử dụng bản thảo này khi bạn biết URL và chỉ cần mở URL đó; nếu không hãy sử dụng setOnClickOpenLinkAction(). Bạn có thể mở URL trong cửa sổ mới hoặc trong lớp phủ. Khi đóng cửa, bạn có thể khiến giao diện người dùng tải lại tiện ích bổ sung.
setSuggestionsAction() Người dùng nhập văn bản vào dữ liệu đầu vào TextInput Đặt một Action thực thi hàm Apps Script khi người dùng nhập văn bản vào một tiện ích nhập văn bản. Trình xử lý tự động chuyển một đối tượng sự kiện vào hàm mà nó gọi. Xem Đề xuất tự động hoàn thành để nhập văn bản để biết thêm chi tiết.

Hàm gọi lại

Các hàm gọi lại sẽ thực thi khi một Action điều kiện kích hoạt. Vì hàm callback là các hàm của Apps Script nên bạn có thể thiết lập các hàm này làm hầu hết mọi thứ mà bất kỳ chức năng nào khác của tập lệnh có thể làm.

Hàm callback đôi khi trả về một đối tượng phản hồi cụ thể. Các các loại phản hồi này chỉ ra các thao tác bổ sung cần thực hiện sau khi lệnh gọi lại hoàn tất việc thực thi, chẳng hạn như hiển thị một thẻ mới hoặc trình bày đề xuất tự động hoàn thành. Khi hàm callback của bạn phải trả về một giá trị cụ thể, phản hồi, bạn sẽ sử dụng một lớp Builder trong Dịch vụ thẻ để tạo đối tượng đó.

Bảng sau đây cho biết thời điểm hàm callback phải trả về một giá trị đối tượng phản hồi cụ thể cho các thao tác cụ thể. Tất cả những thao tác này độc lập với ứng dụng máy chủ cụ thể mà tiện ích bổ sung sẽ mở rộng:

Đã cố gắng thực hiện thao tác Hàm gọi lại cần trả về
Di chuyển giữa các thẻ ActionResponse
Hiển thị Notification ActionResponse
Mở đường liên kết bằng setOnClickOpenLinkAction() ActionResponse
Hiện các đề xuất tự động hoàn thành SuggestionResponse
Sử dụng một hành động chung UniversalActionResponse
Thao tác khác Nothing

Ngoài những tác vụ này, mỗi ứng dụng lưu trữ còn có nhóm mà chỉ có thể thực hiện trong máy chủ đó. Để biết chi tiết, hãy xem hướng dẫn:

Đối tượng sự kiện hành động

Khi tiện ích bổ sung của bạn kích hoạt Action, giao diện người dùng tự động tạo đối tượng sự kiện JSON và truyền đối tượng đó dưới dạng một đối số cho lệnh gọi lại Action . Đối tượng sự kiện này chứa thông tin về hoạt động hiện tại của người dùng ngữ cảnh phía máy khách, chẳng hạn như các giá trị hiện tại của tất cả các tương tác các tiện ích trong thẻ hiển thị.

Các đối tượng sự kiện hành động có một cấu trúc JSON cụ thể giúp sắp xếp thông tin mà chúng chứa. Cấu trúc tương tự này được dùng khi điều kiện kích hoạt trang chủ kích hoạt để tạo trang chủ hoặc khi một điều kiện kích hoạt theo ngữ cảnh kích hoạt để cập nhật màn hình tiện ích bổ sung.

Xem Đối tượng sự kiện để biết đầy đủ nội dung giải thích về cấu trúc đối tượng sự kiện.