Thao tác 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 trường hợp, bạn có thể xác định các thao tác của tiện ích bổ sung bằng cách sử dụng các đối tượng Action 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 một hàm trình xử lý tiện ích thích hợp giúp xác định loại tương tác sẽ 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 sau:
- Tạo đối tượng
Action, chỉ định hàm callback mà đối tượng này sẽ thực thi cùng với mọi tham số yêu cầu. - 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 đối tượng
Action. - 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
Để 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 cần dùng hàm xử lý tiện ích. Hàm xử lý xác định loại tương tác (ví dụ: 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 vi hành động đó. Hàm xử lý cũng xác định các bước mà giao diện người dùng sẽ thực hiện (nếu có) sau khi thao tác đó 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 tiện ích được sử dụng cùng với những trình xử lý đó:
| Hàm trình xử lý | Kích hoạt hành động | Các tiện ích có thể áp dụng | Nội dung mô tả |
|---|---|---|---|
setOnChangeAction() |
Giá trị của tiện ích sẽ thay đổi |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Đặt một Action thực thi hàm Apps Script khi tiện ích này mất tiêu điểm, 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. Trình xử lý tự động truyền một đối tượng sự kiện đến hàm mà trình xử lý gọi.
Nếu muốn, 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. |
setOnClickAction() |
Người dùng nhấp vào tiện ích |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặt một Action thực thi hàm Apps Script khi người dùng nhấp vào tiện ích. Trình xử lý tự động truyền một đối tượng sự kiện đến hàm mà trình xử lý 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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Dành riêng cho Gmail. Đặt một Action tạo thư nháp, sau đó hiển thị thư nháp đó cho người dùng trong cửa sổ soạn thư trên giao diện người dùng của Gmail. Bạn có thể tạo thư nháp dưới dạng thư mới hoặc
thư trả lời cho thư đang mở trong Gmail. Khi gọi hàm callback đang tạo bản nháp, trình xử lý sẽ truyền một đối tượng sự kiện đến hàm callback.
Hãy xem phần Soạn thư nháp để biết thêm chi tiết. |
setOnClickOpenLinkAction() |
Người dùng nhấp vào tiện ích |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặt Action để mở một URL khi người dùng nhấp vào tiện ích. Hãy sử dụng trình xử lý này khi bạn phải tạo URL hoặc phải thực hiện các hành động khác trước khi đường liên kết mở; nếu không, việc dùng setOpenLink() thường sẽ đơn giản hơn.
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Mở trực tiếp một URL khi người dùng nhấp vào tiện ích. Hãy dùng trình xử lý 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, 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ý này tự động truyền một đối tượng sự kiện đến hàm mà nó gọi.
Hãy xem phần Đề xuất tự động hoàn thành cho mục nhập văn bản để biết thêm thông tin 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 kích hoạt. Vì hàm callback là các hàm của Apps Script, nên bạn có thể yêu cầu các hàm này thực hiện hầu hết mọi việc mà các hàm tập lệnh khác có thể làm.
Hàm callback đôi khi trả về một đối tượng phản hồi cụ thể. Các loại phản hồi này cho biết các thao tác khác cần diễn ra sau khi thực thi xong lệnh gọi lại, chẳng hạn như hiển thị một thẻ mới hoặc đưa ra các đề xuất tự động hoàn thành. Khi hàm callback của bạn phải trả về một đối tượng phản hồi cụ thể, bạn sẽ sử dụng lớp trình tạo 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 đối tượng phản hồi cụ thể cho các thao tác cụ thể. Tất cả các thao tác này đều độc lập với ứng dụng máy chủ cụ thể mà tiện ích bổ sung đang 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 thao tác này, mỗi ứng dụng lưu trữ còn có các nhóm thao tác riêng chỉ có thể thực hiện trong máy chủ đó. Để biết thông tin chi tiết, hãy xem hướng dẫn sau:
Đố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 sẽ tự động tạo đối tượng sự kiện JSON và truyền đối tượng đó làm đối số cho hàm callback Action. Đối tượng sự kiện này chứa thông tin về ngữ cảnh phía máy khách hiện tại của người dùng, chẳng hạn như các giá trị hiện tại của tất cả tiện ích tương tác trong thẻ được hiển thị.
Các đối tượng sự kiện hành động có cấu trúc JSON cụ thể sắp xếp thông tin có trong các đối tượng đó. Cấu trúc tương tự được sử dụng khi trình kích hoạt trang chủ kích hoạt để tạo trang chủ hoặc khi đ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.
Hãy xem phần Đối tượng sự kiện để biết nội dung giải thích đầy đủ về cấu trúc đối tượng sự kiện.