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

Trình kích hoạt cho phép Google Apps Script tự động chạy một hàm khi xảy ra một sự kiện nhất định, chẳng hạn như mở tài liệu. Trình 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. Trình kích hoạt có thể cài đặt có nhiều chức năng hơn trình kích hoạt đơn giản nhưng bạn phải 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 cho hàm được kích hoạt một đối tượng sự kiện chứa thông tin về bối cảnh mà sự kiện xảy ra.

Để biết thông tin về cách sử dụng các điều kiện kích hoạt trong dự án tiện ích bổ sung Google Workspace, hãy xem bài viết Điều kiện kích hoạt cho tiện ích bổ sung Google Workspace.

Bắt đầu

Để sử dụng một trình kích hoạt đơn giản, hãy 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) sẽ chạy khi người dùng cài đặ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) 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) 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.

Tham 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ề bối cảnh khiến sự kiện kích hoạt được kích hoạt, nhưng bạn không bắt buộc phải sử dụng đối tượng này.

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 quyền, nên chúng phải tuân thủ một số hạn chế:

• Tập lệnh phải được liên kết với một 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 những ứng dụng đó.
• Các tập lệnh này sẽ không chạy nếu một tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét).
• Việc thực thi tập lệnh và yêu cầu API không khiến các 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 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ì điều đó sẽ yêu cầu uỷ quyền.
• Họ 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 một bộ hạn chế bảo mật phức tạp.
• Quảng cáo này không được chạy quá 30 giây.
• Trong một số trường hợp nhất định, tiện ích bổ sung của 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 uỷ quyền, gây ra một số vấn đề phức tạp 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 trình kích hoạt đơn giản phải tuân theo hạn mức 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)

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, mà chỉ chạy khi mở biểu mẫu để chỉnh sửa.) onOpen(e) thường được dùng nhất để thêm các mục tuỳ chỉnh trong trình đơn vào 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)

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 Editor trong Google Tài liệu, Trang tính, Trang trình bày hoặc Biểu mẫu. Sự kiện kích hoạt này không chạy khi người dùng cài đặt tiện ích bổ sung từ trang web Google Workspace Marketplace. Cách sử dụng phổ biến nhất của onInstall(e) là gọi onOpen(e) để thêm trình đơn tuỳ chỉnh. Sau khi tiện ích bổ sung được cài đặt, tệp đã mở và do đó, onOpen(e) không tự chạy trừ phi tệp được mở lại. Xin lưu ý rằng có một số hạn chế đối với những việc mà onInstall(e) có thể làm. Tìm hiểu thêm về quyền uỷ quyền.

/**
 * 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 trì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 một cách thích hợp. Ví dụ: hàm onEdit(e) bên dưới đặt một chú thích cho ô ghi lại thời điểm 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()}`);
}

Điều kiện kích hoạt onEdit() chỉ xếp hàng tối đa 2 sự kiện kích hoạ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, hãy làm mới bảng tính sau khi thêm điều kiện kích hoạt và mỗi khi mở bảng tính.

Nếu vùng chọn di chuyển giữa nhiều ô trong thời gian ngắn, một số sự kiện thay đổi vùng chọn có thể bị bỏ qua để giảm độ trễ. Ví dụ: nếu có nhiều thay đổi về lựa chọn được thực hiện trong vòng 2 giây, thì chỉ thay đổi về lựa chọn đầu tiên và cuối cùng kích hoạt điều kiện kích hoạt onSelectionChange(e).

Trong ví dụ sau, nếu bạn chọn một ô trống, hàm onSelectionChange(e) sẽ đặt nền của ô 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)

Trình kích hoạt doGet(e) sẽ tự động chạy khi người dùng truy cập vào ứng dụng web hoặc khi một chương trình gửi yêu cầu HTTP GET đến 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 trình kích hoạt này được minh hoạ thêm trong hướng dẫn về ứ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 quy định hạn chế nêu trên.

Các loại điều kiện 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 khiến bạn không đáp ứng được nhu cầu, thì bạn có thể dùng trình kích hoạt có thể cài đặt. Bảng dưới đây tóm tắt những 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ợ các 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ợ các trình kích hoạt mở có thể cài đặt.

Sự kiện	Điều kiện kích hoạt đơn giản	Điều kiện kích hoạt có thể cài đặt
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
Lần gửi biểu mẫu
Dựa trên thời gian (đồng hồ)
Get	function doGet(e)
Đă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ở biểu mẫu để trả lời, mà là khi người chỉnh sửa mở biểu mẫu để sửa đổi.