Các thao tác của 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 thao tác, bạn sẽ xác định những gì 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 các đối tượng Action do Dịch vụ thẻ Google 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 hàm đó. Bạn triển khai hàm callback để thực hiện các bước đã chọ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. Hàm này sẽ 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 theo quy trình 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ố mà đối tượng 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 hiện hành vi bắt buộc.
Đừng nhầm lẫn các đối tượng Action với các đối tượng CardAction. Các đối tượng CardAction là các mục trong trình đơn tiêu đề thẻ, trong khi các đối tượng Action xác định các phản hồi đối với hoạt động tương tác của người dùng với giao diện người dùng.
Hàm trình xử lý tiện ích
Để liên kết một tiện ích với Action hoặc hành vi khác, hãy dùng hàm trình xử lý tiện ích. Hàm trình 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 của thao tác. Hàm trình 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 hoàn tất hành động.
Bảng sau đây liệt kê các loại trình xử lý khác nhau cho tiện ích và tiện ích mà chúng được dùng cùng:
| Hàm trình xử lý | Kích hoạt hành động | Các tiện ích áp dụng | Mô tả |
|---|---|---|---|
setOnChangeAction |
Giá trị của tiện ích thay đổi |
DatePicker
DateTimePicker
SelectionInputSwitch
TextInput
TimePicker
|
Đặt mộ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 đầu vào và nhấn phím 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ề tham số vào đối tượng sự kiện này nếu chọn. |
setOnClickAction |
Người dùng nhấp vào tiện ích |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặt mộ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à nó 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
|
Dành riêng cho Gmail. Đặt một Action tạo bản nháp email, sau đó trình bày bản 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 thư mới hoặc thư trả lời cho thư đang mở trong Gmail. Khi trình xử lý gọi hàm callback 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 bài viết Soạn thảo thư nháp trong Compose để biết thêm thông tin 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 thao tác khác phải diễn ra trước khi đường liên kết mở; nếu không, thường thì bạn chỉ cầ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ể 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 một đầu vào |
TextInput
|
Đặt một Action thực thi một 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à nó gọi.
Hãy xem bài viết Đề xuất tự động hoàn thành cho dữ liệu đầu vào văn bản để biết thêm thông tin chi tiết. |
Hàm gọi lại
Các hàm callback sẽ thực thi khi Action kích hoạt. Vì các hàm gọi lại là hàm 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à bất kỳ hàm tập lệnh nào khác có thể làm.
Đôi khi, hàm callback 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 những thao tác bổ sung cần diễn ra 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ị 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 biết thời điểm các 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 lưu trữ cụ thể mà tiện ích bổ sung đang mở rộng:
| Hành động đã thực hiện | Hàm callback sẽ trả về |
|---|---|
| Điều hướng | ActionResponse |
Hiển thị Notification |
ActionResponse |
Mở đường liên kết bằng cách nhấn tổ hợp phím setOnClickOpenLinkAction |
ActionResponse |
| Hiển thị các đề xuất tự động hoàn thành | SuggestionResponse |
| Sử dụng thao tác chung | UniversalActionResponse |
| Thao tác khác | Nothing |
Các thao tác đối với ứng dụng lưu trữ Google Workspace
Ngoài những thao tác này, mỗi ứng dụng lưu trữ đều có một bộ thao tác riêng mà 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 các hướng dẫn sau:
- Hành động trên Lịch
- Thao tác trong cuộc trò chuyện
- Thúc đẩy hành động
- Thao tác trong Gmail
- Thao tác trên trình chỉnh sửa
Khi sử dụng các lớp trình tạo phản hồi, hãy gọi phương thức build để tạo ra các đối tượng phản hồi. Nếu không làm như vậy, bạn sẽ gặp lỗi.
Thao tác chung được xác định trong tệp kê khai dự án và không cần các đối tượng Action, nhưng các hàm callback của thao tác chung phải trả về một UniversalActionResponse.
Đối tượng sự kiện thao tác
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 đó 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ả các tiện ích tương tác trong thẻ được hiển thị.
Các đối tượng sự kiện thao tác có một cấu trúc JSON cụ thể để sắp xếp thông tin mà chúng chứa. Cấu trúc này cũng đượ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 điều kiện kích hoạt theo bối cảnh kích hoạt để cập nhật màn hình 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.
Tiện ích bổ sung của Gmail sử dụng một phiên bản đơn giản của cấu trúc đối tượng sự kiện này, hiện đã ngừng hoạt động. Để đảm bảo khả năng tương thích ngược, tất cả các trường đối tượng sự kiện của tiện ích bổ sung Gmail ban đầu vẫn nằm trong cấu trúc đối tượng sự kiện mới (xem cấu trúc đối tượng sự kiện).
Tuy nhiên, cùng một thông tin được sao chép trong các cấu trúc con của đối tượng commonEventObject và Gmail event. Nếu bạn đang nâng cấp một tiện ích bổ sung Gmail thành một tiện ích bổ sung Google Workspace, hãy điều chỉnh mã để sử dụng các trường đối tượng sự kiện đã cập nhật. Cuối cùng, các trường đối tượng sự kiện ban đầu của Gmail sẽ bị xoá.