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