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:
- 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. - 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. - 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 |
DatePickerDateTimePickerSelectionInputSwitchTextInput
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặ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 |
CardActionImageImageButtonDecoratedTextTextButton
|
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 |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặ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 |
CardActionImageImageButtonDecoratedTextTextButton
|
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.