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