Trình kích hoạt Apps Script khiến hàm tập lệnh được chỉ định (hàm kích hoạt) thực thi bất cứ khi nào một sự kiện được chỉ định xảy ra. Chỉ một số sự kiện mới có thể kích hoạt trình kích hoạt, và mỗi ứng dụng Google Workspace đều hỗ trợ một nhóm sự kiện khác nhau.
Khi một trình kích hoạt kích hoạt, một đối tượng sự kiện sẽ được tạo. Cấu trúc JSON này chứa thông tin chi tiết về sự kiện đã xảy ra. Thông tin trong cấu trúc đối tượng sự kiện được sắp xếp khác nhau dựa trên loại trình kích hoạt.
Sau khi tạo đối tượng sự kiện, Apps Script sẽ truyền đối tượng đó dưới dạng thông số đến trình kích hoạt. Hàm kích hoạt là một hàm gọi lại mà bạn phải tự triển khai để thực hiện bất kỳ hành động nào phù hợp nhằm phản hồi sự kiện. Chẳng hạn, trong một tiện ích bổ sung của Google Workspace mở rộng Gmail, bạn có thể xác định một trình kích hoạt tạo ra giao diện thẻ mới khi người dùng mở một chuỗi tin nhắn. Trong trường hợp này, bạn triển khai hàm gọi lại theo ngữ cảnh để tạo các thẻ tạo nên giao diện người dùng mới bằng cách sử dụng dữ liệu được truyền trong đối tượng sự kiện.
Trang này cung cấp hướng dẫn về cách sử dụng trình kích hoạt trong các dự án tiện ích bổ sung của Google Workspace.
Trình kích hoạt tệp kê khai
Không giống như tiện ích bổ sung của trình chỉnh sửa, Tiện ích bổ sung của Google Workspace hiện không thể sử dụng trình kích hoạt đơn giản của Apps Script, thay vào đó, chúng sử dụng các trình kích hoạt dành riêng cho Tiện ích bổ sung của Google Workspace: trình kích hoạt tệp kê khai.
Trình kích hoạt tệp kê khai được xác định hoàn toàn trong tệp kê khai của Tiện ích bổ sung Google Workspace. Sau đây là ví dụ về các trình kích hoạt tệp kê khai:
- Trình kích hoạt trang chủ giúp tạo và hiển thị trang chủ tiện ích bổ sung.
- Trình kích hoạt sự kiện Lịch hiển thị một thẻ mới hoặc thực hiện các hành động khác khi sự kiện trên Lịch được mở.
- Trình kích hoạt eventUpdate hiển thị một thẻ mới hoặc thực hiện các hành động khác khi người dùng chỉnh sửa và lưu một sự kiện trên Lịch.
- Trình kích hoạt onItemsSelected trên Drive hiển thị thẻ mới hoặc thực hiện các hành động khác khi người dùng chọn một hoặc nhiều tệp hoặc thư mục trong Drive.
- Trình kích hoạt soạn thư của Gmail hiển thị thẻ tiện ích bổ sung khi người dùng mở tiện ích bổ sung trong cửa sổ soạn thư của Gmail.
- Trình kích hoạt theo ngữ cảnh Gmail hiển thị thẻ mới hoặc thực hiện các hành động khác khi người dùng mở thư Gmail.
- Trình kích hoạt onFileScopeGranted chỉnh sửa sẽ hiển thị một thẻ mới khi người dùng
cấp quyền cho phạm vi OAuth
drive.filetrong tài liệu Trình chỉnh sửa hiện tại.
Trong danh sách trên, chỉ có các trình kích hoạt trang chủ là không có ngữ cảnh; phần còn lại là các trình kích hoạt theo ngữ cảnh. Xem Manifest để biết thêm thông tin về các định nghĩa của trình kích hoạt tệp kê khai.
Ngoài trình kích hoạt tệp kê khai, Tiện ích bổ sung của Google Workspace cũng có thể sử dụng trình kích hoạt có thể cài đặt của Apps Script.
Quy tắc hạn chế
Trình kích hoạt tệp kê khai có một số hạn chế nhất định đối với việc sử dụng.
- Những trình kích hoạt này chỉ được sử dụng trong các dự án Tiện ích bổ sung của Google Workspace; chúng không có mục đích nào trong bất kỳ ứng dụng nào khác.
- Vì được xác định trong tệp kê khai của tiện ích bổ sung chứ không phải trong mã, nên bạn không thể
sử dụng dịch vụ Apps Script
Scriptđể tạo hoặc sửa đổi các trình kích hoạt này. - Trình kích hoạt theo ngữ cảnh của Gmail hiện chỉ có thể có tiêu chí
unconditional. Điều này có nghĩa là trình kích hoạt theo ngữ cảnh kích hoạt cho mọi thư email, bất kể nội dung là gì. - Mỗi tiện ích bổ sung chỉ có thể có một trình kích hoạt cho mỗi loại, mỗi người dùng, cho mỗi tài liệu.