Điều kiện kích hoạt cho phép Apps Script tự động chạy một hàm khi một sự kiện nhất định, chẳng hạn như mở một tài liệu, xảy ra. Điều kiện kích hoạt đơn giản là một tập hợp các hàm dành riêng được tích hợp vào Apps Script, chẳng hạn như hàm onOpen(e)
. Hàm này sẽ thực thi khi người dùng mở một tệp Google Tài liệu, Trang tính, Trang trình bày hoặc Biểu mẫu.
Điều kiện kích hoạt có thể cài đặt cung cấp nhiều khả năng hơn so với điều kiện kích hoạt đơn giản, nhưng phải được kích hoạt trước khi sử dụng. Đối với cả hai loại điều kiện kích hoạt, Apps Script sẽ truyền hàm đã kích hoạt một đối tượng sự kiện chứa thông tin về bối cảnh xảy ra sự kiện.
Bắt đầu
Để sử dụng một điều kiện kích hoạt đơn giản, bạn chỉ cần tạo một hàm sử dụng một trong các tên hàm dành riêng sau:
onOpen(e)
chạy khi người dùng mở một bảng tính, tài liệu, bản trình bày hoặc biểu mẫu mà người dùng có quyền chỉnh sửa.onInstall(e)
chạy khi người dùng cài đặt một Tiện ích bổ sung trình chỉnh sửa trong Google Tài liệu, Trang tính, Trang trình bày hoặc Biểu mẫu.onEdit(e)
chạy khi người dùng thay đổi một giá trị trong bảng tính.onSelectionChange(e)
chạy khi người dùng thay đổi lựa chọn trong bảng tính.doGet(e)
chạy khi người dùng truy cập vào ứng dụng web hoặc một chương trình gửi yêu cầu HTTPGET
đến một ứng dụng web.doPost(e)
chạy khi một chương trình gửi yêu cầu HTTPPOST
đến một ứng dụng web.
Tham số e
trong các tên hàm ở trên là một đối tượng sự kiện được truyền vào hàm. Đối tượng chứa thông tin về ngữ cảnh khiến điều kiện kích hoạt kích hoạt, nhưng không bắt buộc phải sử dụng đối tượng này.
Các quy định hạn chế
Vì các trình kích hoạt đơn giản sẽ tự động kích hoạt mà không cần người dùng cấp phép, nên chúng phải tuân theo một số hạn chế:
- Tập lệnh phải được liên kết với tệp Google Trang tính, Trang trình bày, Tài liệu hoặc Biểu mẫu hoặc là một tiện ích bổ sung mở rộng một trong các ứng dụng đó.
- Chúng không chạy nếu tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét).
- Các quá trình thực thi tập lệnh và yêu cầu API không khiến trình kích hoạt chạy. Ví dụ: việc gọi
Range.setValue()
để chỉnh sửa một ô sẽ không khiến trình kích hoạtonEdit
của bảng tính chạy. - Họ không thể truy cập vào các dịch vụ yêu cầu uỷ quyền. Ví dụ: một điều kiện kích hoạt đơn giản không thể gửi email vì dịch vụ Gmail yêu cầu uỷ quyền, nhưng một điều kiện kích hoạt đơn giản có thể dịch một cụm từ bằng dịch vụ Ngôn ngữ (ẩn danh).
- Họ có thể sửa đổi tệp mà chúng được liên kết, nhưng không thể truy cập vào các tệp khác vì việc đó sẽ cần được cho phép.
- Các trình xử lý này có thể xác định hoặc không xác định được danh tính của người dùng hiện tại, tuỳ thuộc vào nhóm hạn chế phức tạp về bảo mật.
- Quảng cáo này không thể chạy lâu hơn 30 giây.
- Trong một số trường hợp, Tiện ích bổ sung trình chỉnh sửa sẽ chạy các trình kích hoạt đơn giản
onOpen(e)
vàonEdit(e)
ở chế độ không cấp quyền. Tiện ích này hiển thị thêm một số chức năng. Để biết thêm thông tin, hãy xem hướng dẫn về vòng đời uỷ quyền của tiện ích bổ sung. - Các điều kiện kích hoạt đơn giản phải tuân theo giới hạn hạn mức của trình kích hoạt Apps Script.
Những hạn chế này không áp dụng cho doGet(e)
hoặc doPost(e)
.
onOpen(e)
Điều kiện kích hoạt onOpen(e)
sẽ tự động chạy khi người dùng mở một bảng tính, tài liệu, bản trình bày hoặc biểu mẫu mà họ có quyền chỉnh sửa. (Trình kích hoạt không chạy khi phản hồi biểu mẫu, chỉ chạy khi mở biểu mẫu để chỉnh sửa biểu mẫu đó.) onOpen(e)
thường được dùng để thêm các mục trong trình đơn tuỳ chỉnh vào Google Trang tính, Trang trình bày, Tài liệu hoặc Biểu mẫu.
onInstall(e)
Trình kích hoạt onInstall(e)
sẽ tự động chạy khi người dùng cài đặt Tiện ích bổ sung trình chỉnh sửa trong Google Tài liệu, Trang tính, Trang trình bày hoặc Biểu mẫu. Trình kích hoạt sẽ không chạy khi người dùng cài đặt tiện ích bổ sung trên trang web Google Workspace Marketplace. Lưu ý rằng có một số hạn chế nhất định về những việc onInstall(e)
có thể làm, tìm hiểu thêm về uỷ quyền.
Cách sử dụng phổ biến nhất của onInstall(e)
chỉ đơn giản là gọi onOpen(e)
để thêm các trình đơn tuỳ chỉnh. Xét cho cùng, khi một tiện ích bổ sung được cài đặt, tệp đã mở và do đó onOpen(e)
sẽ không tự chạy trừ phi tệp được mở lại.
onEdit(e)
Điều kiện kích hoạt onEdit(e)
sẽ tự động chạy khi người dùng thay đổi giá trị của bất kỳ ô nào trong bảng tính. Hầu hết điều kiện kích hoạt onEdit(e)
đều sử dụng thông tin trong đối tượng sự kiện để phản hồi một cách thích hợp.
Ví dụ: hàm onEdit(e)
bên dưới đặt một nhận xét trên ô ghi lại lần chỉnh sửa gần đây nhất.
onSelectionChange(e)
Trình kích hoạt onSelectionChange(e)
sẽ tự động chạy khi người dùng thay đổi lựa chọn trong bảng tính. Để kích hoạt điều kiện kích hoạt này, bạn phải làm mới bảng tính sau khi điều kiện kích hoạt được thêm và mỗi khi bảng tính được mở.
Nếu lựa chọn di chuyển giữa nhiều ô trong một thời gian ngắn, thì một số sự kiện thay đổi lựa chọn có thể bị bỏ qua để giảm độ trễ. Ví dụ: nếu nhiều thay đổi lựa chọn được thực hiện trong vòng 2 giây với nhau, thì chỉ những thay đổi về lựa chọn đầu tiên và cuối cùng mới kích hoạt điều kiện kích hoạt onSelectionChange(e)
.
Trong ví dụ bên dưới, nếu một ô trống được chọn thì hàm onSelectionChange(e)
sẽ đặt nền của ô thành màu đỏ.
doGet(e)
và doPost(e)
Trình kích hoạt doGet(e)
sẽ tự động chạy khi người dùng truy cập ứng dụng web hoặc chương trình gửi yêu cầu HTTP GET
đến ứng dụng web. doPost(e)
chạy khi chương trình gửi yêu cầu HTTP POST
đến ứng dụng web. Bạn có thể xem thêm các điều kiện kích hoạt này trong hướng dẫn tới ứng dụng web, dịch vụ HTML và Dịch vụ nội dung. Xin lưu ý rằng doGet(e)
và doPost(e)
không phải tuân theo các hạn chế nêu trên.
Các loại trình kích hoạt hiện có
Nếu hạn chế đối với điều kiện kích hoạt đơn giản ngăn chúng đáp ứng nhu cầu của bạn, thì một điều kiện kích hoạt có thể cài đặt có thể hoạt động. Bảng dưới đây tóm tắt các loại điều kiện kích hoạt có sẵn cho từng loại sự kiện. Ví dụ: Google Trang tính, Trang trình bày, Biểu mẫu và Tài liệu đều hỗ trợ điều kiện kích hoạt mở đơn giản, nhưng chỉ Trang tính, Tài liệu và Biểu mẫu mới hỗ trợ điều kiện kích hoạt mở có thể cài đặt.
Sự kiện | Trình kích hoạt đơn giản | Trình kích hoạt có thể cài đặt |
---|---|---|
Đang mở |
|
|
Chỉnh sửa |
|
|
Thay đổi lựa chọn |
|
|
Cài đặt |
|
|
Chuyển |
|
|
Gửi biểu mẫu |
|
|
Theo thời gian (đồng hồ) |
|
|
Get |
|
|
Bài đăng |
|
* Sự kiện mở cho Google Biểu mẫu không xảy ra khi người dùng mở biểu mẫu để phản hồi, mà xảy ra khi người chỉnh sửa mở biểu mẫu để sửa đổi biểu mẫu đó.