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