Thao tác với tiện ích bổ sung

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 của 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 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 đã 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 kích hoạt lệnh gọi lại Action.

Định cấu hình một tiện ích bằng Action theo quy trình chung sau:

1. 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 yêu cầu.
2. Gọi hàm trình xử lý tiện ích thích hợp trên tiện ích bằng đối tượng Action.
3. Triển khai hàm gọi lại để thực hiện hành vi bắt buộc.

Lưu ý: Đừ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 một Action cụ thể hoặc hành vi khác, bạn sẽ sử 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) sẽ kích hoạt hành vi của thao tác. Hàm trình 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 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 SelectionInput Switch 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ề thông 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	CardAction Image ImageButton DecoratedText TextButton	Đặ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à 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	CardAction Image ImageButton DecoratedText TextButton	Dành riêng cho Gmail. Đặt một Action tạo thư nháp, sau đó trình bày 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 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 gọi lại tạo bản nháp, trình xử lý sẽ truyền một đối tượng sự kiện đến hàm gọi lại. 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	CardAction Image ImageButton DecoratedText TextButton	Đặ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	CardAction Image ImageButton DecoratedText TextButton	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à trình xử lý 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ì hàm gọi lại 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.

Cảnh báo: Dịch vụ Thẻ của Apps Script giới hạn thời gian thực thi tối đa của các hàm gọi lại là 30 giây. Nếu quá trình thực thi mất nhiều thời gian hơn, thì giao diện người dùng của tiện ích bổ sung có thể không cập nhật đúng cách chế độ hiển thị thẻ để phản hồi Action.

.

Đô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 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 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 các hàm gọi lại 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 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 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 đối với ứng dụng Chat
• Thúc đẩy hành động
• Thao tác trong Gmail
• Thao tác của người chỉnh sửa

Lưu ý: Khi sử dụng các lớp trình tạo phản hồi, hãy nhớ gọi 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.

Lưu ý: 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 gọi lại của thao tác chung phải trả về 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 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ư 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 tương tự đượ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 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.

Lưu ý: Tiện ích bổ sung Gmail đã sử dụng 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. Để có 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 sự kiện chung và sự kiện trên Gmail. Nếu đang nâng cấp một tiện ích bổ sung Gmail thành tiện ích bổ sung Google Workspace, bạn nên đ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á.