Điều kiện 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 xảy ra sự kiện được chỉ định. Chỉ một số sự kiện có thể khiến điều kiện kích hoạt 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, hệ thống sẽ tạo một đối tượng sự kiện. 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 đối tượng sự kiện được tạo, Apps Script sẽ truyền đối tượng đó dưới dạng thông số cho hàm của trình kích hoạt. Hàm kích hoạt là hàm callback mà bạn phải tự triển khai để thực hiện bất kỳ hành động nào thích hợp nhằm phản hồi sự kiện đó. Ví dụ: trong một Tiện ích bổ sung của Google Workspace mở rộng Gmail, bạn có thể xác định 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 thư. Trong trường hợp này, bạn sẽ triển khai hàm callback 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 vào đối tượng sự kiện.
Trang này cung cấp nguyên tắc về cách sử dụng điều kiện 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ác với Tiện ích bổ sung dành cho Trình chỉnh sửa, Tiện ích bổ sung Google Workspace hiện không thể sử dụng các trình kích hoạt đơn giản của Apps Script Thay vào đó, các tiện ích này sử dụng trình kích hoạt được thiết kế 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ề trình kích hoạt tệp kê khai:
- Trình kích hoạt trang chủ tạo và hiển thị trang chủ tiện ích bổ sung.
- Điều kiện kích hoạt sự kiện Lịch Open hiển thị một thẻ mới hoặc thực hiện các hành động khác khi một sự kiện trên Lịch được mở.
- Trình kích hoạt Cập nhật sự kiện lịch hiển thị thẻ mới hoặc thực hiện các thao tác khác khi người dùng chỉnh sửa và lưu một sự kiện trên Lịch.
- Điều kiện kích hoạt onItemsSelected hiển thị thẻ mới hoặc thực hiện các thao tác khác khi người dùng chọn một hoặc nhiều tệp hay 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 của Gmail hiển thị thẻ mới hoặc thực hiện các thao tác khác khi người dùng mở thư trên Gmail.
- Trình kích hoạt onFileScopeGranted 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 hiện tại về Trình chỉnh sửa.
Trong danh sách trên, chỉ các trình kích hoạt trang chủ là không theo ngữ cảnh; phần còn lại là trình kích hoạt theo ngữ cảnh. Xem Tệp kê khai để biết thêm thông tin về định nghĩa trình kích hoạt tệp kê khai.
Ngoài điều kiện kích hoạt tệp kê khai, các tiện ích bổ sung của Google Workspace cũng có thể sử dụng điều kiện kích hoạt có thể cài đặt của Apps Script.
Quy định hạn chế
Điều kiện 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 dùng trong các dự án Tiện ích bổ sung của Google Workspace; chúng không có mục đích gì trong bất kỳ ứng dụng nào khác.
- Vì các trình kích hoạt này được xác định trong tệp kê khai tiện ích bổ sung chứ không phải trong mã của tiện ích bổ sung, nên bạn không thể sử dụng dịch vụ Apps Script
Scriptđể tạo hoặc sửa đổi những 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 sẽ kích hoạt cho mọi email, bất kể nội dung. - Mỗi tiện ích bổ sung chỉ có thể có một trình kích hoạt cho mỗi loại, cho mỗi người dùng và trên mỗi tài liệu.