Các thao tác 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 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 của tiện ích bổ sung bằng cách sử dụng
Action
các đối tượng do dịch vụ Thẻ của 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 thao tác đó. 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 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
theo quy trình sau:
- Tạo đối tượng
Action, chỉ định hàm callback mà đối tượng đó sẽ thực thi cùng với mọi tham số 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 đố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 Action
đối tượng với CardAction
đối tượng. CardAction
đối tượng là các mục trong trình đơn tiêu đề thẻ, trong khi
Action đối tượng xác định
các phản hồi đối với lượt tương tác của người dùng với giao diện người dùng.
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, hãy sử dụng hàm xử lý tiện ích. 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 thao tác. 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 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à các tiện ích mà chúng được dùng:
| Hàm xử lý | Kích hoạt thao tác | Tiện ích áp dụng | Mô tả |
|---|---|---|---|
setOnChangeAction |
Giá trị tiện ích thay đổi |
DatePicker
DateTimePicker
SelectionInputSwitch
TextInput
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 một trường 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 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 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
|
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ư trên 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 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.
Xem
bài viết Soạn thư nháp
để biết thêm thông tin. |
setOnClickOpenLinkAction |
Người dùng nhấp vào tiện ích |
CardActionImageImageButtonDecoratedTextTextButton
|
Đặt một Action
để mở 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 sẽ đơn giản hơn khi 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 trường nhập |
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.
Xem bài viết
Đề xuất tự động hoàn thành
cho trường nhập văn bản để biết thêm thông tin. |
Hàm callback
Hàm callback thực thi khi an
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à bất kỳ hàm tập lệnh nào khác có thể thực hiện.
Đôi khi, hàm callback 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 diễn ra sau khi lệnh gọi lại thực thi xong, 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 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 callback phải trả về một đối tượng phản hồi cụ thể cho các thao tác cụ thể. 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:
| Thao tác đã thử | Hàm callback sẽ trả về |
|---|---|
| Điều hướng | ActionResponse |
Hiển thị Notification |
ActionResponse |
Mở một đường liên kết bằng setOnClickOpenLinkAction |
ActionResponse |
| Hiển thị các đề xuất tự động hoàn thành | SuggestionResponse |
| Sử dụng một thao tác phổ biến | UniversalActionResponse |
| Thao tác khác | Nothing |
Thao tác cho các ứng dụng lưu trữ Google Workspace
Ngoài các thao tác này, mỗi ứng dụng lưu trữ có một tập hợp các thao tác riêng 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:
- Thao tác trên Lịch
- Thao tác trên Chat
- Thao tác trên Drive
- Thao tác trên 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 đối tượng phản hồi. Nếu không thực hiện, bạn sẽ gặp lỗi.
Các thao tác phổ biến được xác định
trong tệp kê khai dự án và không cần
Action đối tượng, nhưng hàm callback của các thao tác này phải trả về
UniversalActionResponse.
Đối tượng sự kiện thao tác
Khi tiện ích bổ sung 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ề 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ị.
Đố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 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 trình kích hoạt theo bối cảnh kích hoạt để cập nhật màn hình tiện ích bổ sung.
Xem bài viết Đối tượng sự kiện để biết giải thích đầy đủ về cấu trúc đối tượng sự kiện.
Tiện ích bổ sung 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 không được dùng nữa. Để đả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, thông tin tương tự được sao chép trong các cấu trúc con commonEventObject
và đối tượng sự kiện Gmail. Nếu bạn đang nâng cấp tiện ích bổ sung Gmail thành 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 Gmail ban đầu sẽ bị xoá.