Trang này được dịch bởi Cloud Translation API.

Các trình kích hoạt đơn giản

Các trình 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. Trình kích hoạt đơn giản là một tập hợp các hàm được đặt trước được tích hợp vào Apps Script, chẳng hạn như hàm onOpen(e), hàm này thực thi khi người dùng mở tệp 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 có thể cài đặt mang lại nhiều khả năng hơn so với trình 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 trình kích hoạt, Apps Script sẽ truyền hàm được kích hoạt một đối tượng sự kiện chứa thông tin về ngữ cảnh xảy ra sự kiện.

Bắt đầu

Để sử dụng trình 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 đặt trước sau:

onOpen(e) chạy khi người dùng mở 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 của 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 ứ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 một chương trình gửi yêu cầu HTTP POST đến một ứng dụng web.

Thông số e trong tên hàm ở trên là một đối tượng sự kiện được truyền đến hàm. Đối tượng này chứa thông tin về ngữ cảnh khiến trình kích hoạt kích hoạt, nhưng bạn không bắt buộc phải sử dụng đối tượng đó.

Quy tắc hạn chế

Vì các lệnh kích hoạt đơn giản tự động kích hoạt mà không yêu cầu người dùng uỷ quyền, nên họ sẽ 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, nếu không thì đó 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).
Việc thực thi tập lệnh và các 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 ô không khiến trình kích hoạt onEdit 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 trình kích hoạt đơn giản không thể gửi email vì dịch vụ Gmail cần được cho phép, nhưng một trình kích hoạt đơn giản có thể dịch một cụm từ bằng dịch vụ Ngôn ngữ ở chế độ ẩn danh.
Họ có thể sửa đổi tệp mà họ được liên kết, nhưng không thể truy cập vào các tệp khác vì thao tác này sẽ yêu cầu uỷ quyền.
Có thể họ có thể hoặc không thể xác định danh tính của người dùng hiện tại, tuỳ thuộc vào một bộ hạn chế bảo mật phức tạp.
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 nhất định, các tiện ích bổ sung dành cho trình chỉnh sửa chạy các trình kích hoạt đơn giản onOpen(e) và onEdit(e) ở chế độ không cho phép sẽ 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 bổ sung.
Các trình kích hoạt đơn giản phải tuân theo giới hạn định mức của trình kích hoạt Apps Script.

Những quy định hạn chế này không áp dụng cho doGet(e) hoặc doPost(e).

`onOpen(e)`

Trình 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ỉ khi mở biểu mẫu để chỉnh sửa biểu mẫu.) onOpen(e) thường được dùng để thêm mục 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.

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

`onInstall(e)`

Trình kích hoạt onInstall(e) sẽ tự động chạy khi người dùng cài đặt một tiện ích bổ sung của 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 từ trang web Google Workspace Marketplace. Lưu ý rằng có một số hạn chế nhất định về những gì onInstall(e) có thể làm, tìm hiểu thêm về uỷ quyền. Cách sử dụng onInstall(e) phổ biến nhất chỉ đơn giản là gọi onOpen(e) để thêm trình đơn tuỳ chỉnh. Khi tệp cài đặt tiện ích bổ sung, tệp đó sẽ mở ra, do đó, onOpen(e) không thể tự chạy trừ phi bạn mở lại tệp đó.

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

`onEdit(e)`

Trình 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 các lệnh kích hoạt onEdit(e) đều sử dụng thông tin trong đối tượng sự kiện để phản hồi 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.

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

`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 trình kích hoạt này, bạn phải làm mới bảng tính sau khi thêm trình kích hoạt và mỗi khi mở bảng tính.

Nếu lựa chọn di chuyển giữa nhiều ô trong một thời gian ngắn, 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 hai giây của nhau, thì chỉ những thay đổi lựa chọn đầu tiên và cuối cùng sẽ kích hoạt trình kích hoạt onSelectionChange(e).

Trong ví dụ bên dưới, nếu bạn chọn một ô trống, hàm onSelectionChange(e) sẽ đặt nền của ô thành màu đỏ.

trình kích hoạt/trình kích hoạt.gs

Xem trên GitHub

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

`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 vào một ứng dụng web hoặc một chương trình gửi yêu cầu HTTP GET đến một ứng dụng web. doPost(e) chạy khi một chương trình gửi yêu cầu HTTP POST đến một ứng dụng web. Các trình kích hoạt này được minh hoạ chi tiết hơn trong hướng dẫn về các ứng dụng web, dịch vụ HTML và Dịch vụ nội dung , Lưu ý rằng doGet(e) và doPost(e) không phải tuân theo các quy định hạn chế nêu trên.

Các loại trình kích hoạt có sẵn

Nếu các hạn chế đối với trình kích hoạt đơn giản ngăn chúng đáp ứng nhu cầu của bạn, thì trình kích hoạt có thể cài đặt có thể hoạt động thay thế. Bảng bên dưới tóm tắt những loại trình 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ợ trình kích hoạt mở đơn giản, nhưng chỉ Trang tính, Tài liệu và Biểu mẫu hỗ trợ trình kích hoạt mở có thể cài đặt.

Event (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ở	Trang tính Trang trình bày Biểu mẫu* Tài liệu `function onOpen(e)`	Trang tính Biểu mẫu* Tài liệu
Chỉnh sửa	Trang tính `function onEdit(e)`	Trang tính
Thay đổi lựa chọn	Trang tính `function onSelectionChange(e)`
Cài đặt	Trang tính Trang trình bày Biểu mẫu Tài liệu `function onInstall(e)`
Chuyển		Trang tính
Gửi biểu mẫu		Trang tính Biểu mẫu
Theo thời gian (đồng hồ)		Trang tính Trang trình bày Biểu mẫu Tài liệu Trang web Độc lập
Get	Trang web Độc lập `function doGet(e)`
Bài đăng	Trang web Độc lập `function doPost(e)`