Trình kích hoạt đơn giản

Trình kích hoạt cho phép Apps Script tự động chạy một chức năng khi một sự kiện nhất định, chẳng hạn như mở tài liệu. Điều kiện kích hoạt đơn giản là một tập hợp chức năng dành riêng được tích hợp vào Apps Script, chẳng hạn như hàm onOpen(e), lệnh 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 lợi ích hơn các chức năng khác 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. Cho cả hai các loại kích hoạt, Apps Script sẽ truyền hàm được kích hoạt đối tượng sự kiện chứa thông tin về bối cảnh mà sự kiện đã xảy ra.

Bắt đầu

Để sử dụng một trình kích hoạt đơn giản, bạn chỉ cần tạo hàm sử dụng một trong các trình kích hoạt này tên hàm dành riêng:

• onOpen(e) sẽ chạy khi người dùng mở bảng tính, tài liệu, bản trình bày hoặc mà người dùng có quyền chỉnh sửa.
• onInstall(e) sẽ 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) sẽ chạy khi người dùng thay đổi một giá trị trong bảng tính.
• onSelectionChange(e) sẽ chạy khi người dùng thay đổi lựa chọn trong bảng tính.
• doGet(e) sẽ chạy khi người dùng truy cập vào ứng dụng web hoặc một chương trình sẽ gửi yêu cầu HTTP GET đến ứng dụng web.
• doPost(e) sẽ chạy khi một chương trình gửi yêu cầu HTTP POST đến một ứng dụng web.

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

Quy định hạn chế

Bởi vì các điều kiện kích hoạt đơn giản tự động kích hoạt mà không cần yêu cầu người dùng phải tuân theo một số hạn chế sau:

• Tập lệnh phải được liên kết với Trang tính, Trang trình bày, Tài liệu hoặc Biểu mẫu hoặc tệp khác là tiện ích bổ sung mở rộng một trong các ứng dụng đó.
• Các hàm này 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 điều kiện kích hoạt chạy. Ví dụ: đang gọi Range.setValue() để chỉnh sửa một ô thì điều này không làm cho trình kích hoạt onEdit của bảng tính chạy.
• Họ không thể truy cập 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 yêu cầu uỷ quyền, 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ữ, ẩ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ì việc đó sẽ yêu cầu uỷ quyền.
• Họ có thể hoặc không thể xác định danh tính của người dùng hiện tại, tùy thuộc vào một bộ giới hạn bảo mật phức tạp.
• Quảng cáo không được chạy lâu hơn 30 giây.
• Trong một số trường hợp, Tiện ích bổ sung dành cho trình chỉnh sửa chạy onOpen(e) và onEdit(e) trình kích hoạt đơn giản ở chế độ không cấp phép một số chức năng khác. Để 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ụ thuộc vào điều kiện kích hoạt Apps Script hạn mức.

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. (Các điều kiện kích hoạt không chạy khi phản hồi một biểu mẫu, mà chỉ chạy khi bạn mở biểu mẫu để chỉnh sửa.) onOpen(e) thường được dùng nhất để thêm tuỳ chỉnh các mục trong trình đơn sang Google Trang tính, Trang trình bày, Tài liệu hoặc Biểu mẫu.

/**
 * 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)

Điều kiện 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 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. Điều kiện kích hoạt sẽ không chạy khi người dùng cài đặt tiện ích bổ sung đó từ Google Workspace Marketplace của bạn. 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 trình đơn tuỳ chỉnh. Rốt cuộc, khi một tiện ích bổ sung được cài đặt, tệp sẽ mở ra, và do đó onOpen(e) không tự chạy trừ phi tệp được mở lại.

/**
 * 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)

Đ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ỳ ô 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 phù hợp. Ví dụ: hàm onEdit(e) bên dưới đặt nhận xét trên ô ghi lại lần chỉnh sửa gần đây nhất.

/**
 * 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)

Điều kiện 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 sau khi thêm trình kích hoạt 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, một số lựa chọn các sự kiện thay đổi khác có thể bị bỏ qua để giảm độ trễ. Ví dụ: nếu nhiều lựa chọn các thay đổi được thực hiện trong vòng hai giây với nhau, chỉ có sự thay đổi đầu tiên và cuối cùng Các thay đổi về lựa chọn 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 giá trị nền thành màu đỏ.

/**
 * 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)

Điều kiện 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 vào một ứng dụng web. doPost(e) sẽ 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 yếu tố kích hoạt này được minh hoạ nhiều hơn trong hướng dẫn về ứ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 điều kiện kích hoạt hiện có

Nếu các hạn chế đối với trình kích hoạt đơn giản ngăn chúng họp nhu cầu của bạn, một điều kiện kích hoạt có thể cài đặt có thể hiệu quả thay thế. Bảng bên dưới tóm tắt các loại điều kiện kích hoạt dành 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ất cả Tài liệu đều hỗ trợ các trình kích hoạt mở đơn giản, nhưng chỉ hỗ trợ Trang tính, Tài liệu và Biểu mẫu các đ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	Điều kiện kích hoạt có thể cài đặt
Đang mở	function onOpen(e)
Chỉnh sửa	function onEdit(e)
Thay đổi lựa chọn	function onSelectionChange(e)
Cài đặt	function onInstall(e)
Chuyển
Gửi biểu mẫu
Theo thời gian (đồng hồ)
Get	function doGet(e)
Bài đăng	function doPost(e)

* Sự kiện mở cho Google Biểu mẫu không xảy ra khi người dùng mở một biểu mẫu để phản hồi, mà là khi người chỉnh sửa mở biểu mẫu để sửa đổi biểu mẫu đó.