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

Điều kiện kích hoạt cho phép Google 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. Đ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 tính năng hơn đ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 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 điều kiện kích hoạt trong các dự án tiện ích bổ sung dành cho Google Workspace, hãy xem bài viết Điều kiện kích hoạt cho tiện ích bổ sung dành cho Google Workspace.

Bắt đầu

Để sử dụng điều kiện 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) 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 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 điều 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ì điều kiện kích hoạt đơn giản tự động kích hoạt mà không yêu cầu 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 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 phải 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 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 điều kiện kích hoạt chạy. Ví dụ: việc gọi Range.setValue() để chỉnh sửa một ô không khiến điều kiện kích hoạt onEdit của bảng tính chạy.
  • Chúng không thể truy cập vào các dịch vụ yêu cầu cấp quyền. Ví dụ: đ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 cấp quyền, nhưng đ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ữ (dịch vụ này là ẩn danh).
  • Chúng 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ẽ yêu cầu cấp quyền.
  • Chúng 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, tùy thuộc vào một tập hợp phức tạp các quy định hạn chế về bảo mật.
  • Chúng 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 cho Trình chỉnh sửa chạy điều kiện kích hoạt đơn giản onOpen(e) và onEdit(e) ở chế độ không cấp 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 cấp quyền cho tiện ích bổ sung.
  • Điều kiện kích hoạt đơn giản phải tuân theo các giới hạn về hạn mức điều kiện kích hoạt của 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)

Điều kiện kích hoạt onOpen(e) 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. (Điều kiện 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 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.

triggers/triggers.gs
/**
 * 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) 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 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 cài đặt một tiện ích bổ sung, tệp đã được mở, 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ố quy định hạn chế về những việc mà onInstall(e) có thể làm. Tìm hiểu thêm về việc cấp quyền.

triggers/triggers.gs
/**
 * 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) 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 thời điểm chỉnh sửa gần đây nhất.

triggers/triggers.gs
/**
 * 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)

Điều kiện kích hoạt onSelectionChange(e) 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 lựa chọn di chuyển giữa nhiều ô trong một khoảng 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 có nhiều thay đổi lựa chọn được thực hiện trong vòng 2 giây, thì chỉ những thay đổi 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ụ sau, nếu một ô trống được chọn, thì hàm onSelectionChange(e) sẽ đặt nền của ô thành màu đỏ.

triggers/triggers.gs
/**
 * 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) 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 điều kiện 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ế được liệt kê ở trên.

Các loại điều kiện kích hoạt có sẵn

Nếu các quy định hạn chế đối với điều kiện kích hoạt đơn giản khiến chúng không đáp ứng được nhu cầu của bạn, thì bạn có thể sử dụng điều kiện kích hoạt có thể cài đặt thay thế. Bảng bên dưới tóm tắt những loại điều kiện kích hoạt có thể sử dụng 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 hỗ trợ điều kiện 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ở
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
Độc lập
Get
Độc lập

function doGet(e)
Đăng
Độc lập

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à xảy ra khi một trình chỉnh sửa mở biểu mẫu để sửa đổi.