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 hàm khi một sự kiện nhất định xảy ra, chẳng hạn như mở một tài liệu. Trình kích hoạt đơn giản là một tập hợp các hàm được đặt trước tích hợp sẵn trong 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ở 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 cung cấp nhiều tính năng hơn so với trình kích hoạt đơn giản, nhưng bạn phải kích hoạt trình kích hoạt này 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 một 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 được đặt trước sau đây:

• 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 cho 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 một ứng dụng web hoặc một chương trình gửi yêu cầu GET HTTP đến một ứng dụng web.
• doPost(e) chạy khi một chương trình gửi yêu cầu POST HTTP đế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 vào hàm. Đối tượng này chứa thông tin về ngữ cảnh đã kích hoạt điều kiện 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 theo một số quy định 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 đó.
• Các macro này sẽ không chạy nếu tệp được mở ở chế độ chỉ có thể đọc (xem hoặc nhận xét).
• Các lệ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ụ: việc gọi Range.setValue() để chỉnh sửa một ô sẽ không khiến điều kiện kích hoạt onEdit của bảng tính chạy.
• Các ứng dụng này không thể truy cập vào các dịch vụ yêu cầu quyền 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.
• Các tệp này có thể sửa đổi tệp mà chúng liên kết, nhưng không thể truy cập vào các tệp khác vì cần có quyền uỷ quyền.
• Các ứng dụng này có thể xác định được 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ộ quy định hạn chế bảo mật phức tạp.
• Quảng cáo này 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 cho trình chỉnh sửa sẽ chạy trình kích hoạt đơn giản onOpen(e) và onEdit(e) ở chế độ không uỷ quyền, cho thấy một số chức năng bổ sung. Để biết thêm thông tin, hãy xem hướng dẫn về vòng đời uỷ quyền tiện ích bổ sung.
• Trình 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.

Các 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 một biểu mẫu, chỉ chạy khi mở biểu mẫu để chỉnh sửa.) 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.

/**
 * 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 cho 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ừ trang web Google Workspace Marketplace. Xin lưu ý rằng có một số quy định hạn chế đối với những việc onInstall(e) có thể làm. Hãy tìm hiểu thêm về quyền uỷ quyền. Cách sử dụng phổ biến nhất của onInstall(e) chỉ là gọi onOpen(e) để thêm 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ì vậy onOpen(e) không tự chạy trừ khi 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)

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 nhận xét trên ô ghi lại lần gần đây nhất ô đó được chỉnh sửa.

/**
 * 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 điều kiện kích hoạt này, bạn phải 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 lựa chọn di chuyển giữa nhiều ô trong một khoảng 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 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 mới kích hoạt điều kiện kích hoạt onSelectionChange(e).

Trong ví dụ dưới đây, 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 một ứng dụng web hoặc một chương trình gửi yêu cầu GET HTTP đế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 POST HTTP đến một ứng dụng web. Bạn có thể xem thêm về các trình kích hoạt này 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 chịu 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 khiến chúng không đáp ứng được nhu cầu của bạn, thì trình kích hoạt có thể cài đặt có thể hoạt động. 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 mới hỗ trợ 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	Trình 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
Do thời gian điều khiển (đồ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ở biểu mẫu để trả lời, mà là khi người chỉnh sửa mở biểu mẫu để sửa đổi biểu mẫu đó.