简单触发器

借助触发器，您可以让 Apps 脚本在发生特定事件（例如打开文档）时自动运行函数。简单触发器是 Google Apps 脚本中内置的一组预留函数，例如函数 onOpen(e)，该函数会在用户打开 Google 文档、表格、幻灯片或表单文件时执行。可安装的触发器比简单触发器提供更多功能，但必须先激活才能使用。对于这两种类型的触发器，Apps Script 都会向触发的函数传递一个事件对象，其中包含与事件发生情境相关的信息。

使用入门

如需使用简单触发器，只需创建一个使用以下某个预留函数名称的函数即可：

• 当用户打开有权编辑的电子表格、文档、演示文稿或表单时，系统会运行 onOpen(e)。
• 当用户在 Google 文档、表格、幻灯片或表单中安装编辑器插件时，系统会运行 onInstall(e)。
• 当用户更改电子表格中的值时，系统会运行 onEdit(e)。
• 当用户更改电子表格中的选择时，系统会运行 onSelectionChange(e)。
• 当用户访问Web 应用或程序向 Web 应用发送 HTTP GET 请求时，doGet(e) 就会运行。
• 当程序向 Web 应用发送 HTTP POST 请求时，doPost(e) 会运行。

上述函数名称中的 e 参数是传递给函数的事件对象。该对象包含导致触发器触发的上下文的相关信息，但使用该对象并非强制性要求。

限制

由于简单触发器会自动触发，而无需向用户请求授权，因此受到以下几项限制：

• 脚本必须绑定到 Google 表格、幻灯片、文档或表单文件，或者是用于扩展其中某个应用的插件。
• 如果文件以只读（查看或评论）模式打开，则不会运行这些脚本。
• 脚本执行和 API 请求不会导致触发器运行。例如，调用 Range.setValue() 来修改单元格不会导致电子表格的 onEdit 触发器运行。
• 他们无法访问需要授权的服务。例如，简单触发器无法发送电子邮件，因为 Gmail 服务需要授权，但简单触发器可以使用匿名的语言服务来翻译短语。
• 他们可以修改其关联的文件，但无法访问其他文件，因为这需要获得授权。
• 它们能否确定当前用户的身份取决于一组复杂的安全限制。
• 其播放时长不得超过 30 秒。
• 在某些情况下，编辑器插件会在无授权模式下运行其 onOpen(e) 和 onEdit(e) 简单触发器，这会带来一些额外的复杂性。如需了解详情，请参阅插件授权生命周期指南。
• 简单触发器受 Apps 脚本触发器配额限制的约束。

这些限制不适用于 doGet(e) 或 doPost(e)。

onOpen(e)

当用户打开有权修改的电子表格、文档、演示文稿或表单时，onOpen(e) 触发器会自动运行。（在回复表单时，触发器不会运行，只有在打开表单进行修改时才会运行。）onOpen(e) 最常用于向 Google 表格、幻灯片、文档或表单添加自定义菜单项。

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

当用户在 Google 文档、表格、幻灯片或表单中安装编辑器插件时，onInstall(e) 触发器会自动运行。当用户从 Google Workspace Marketplace 网站安装该插件时，触发器不会运行。请注意，onInstall(e) 可以执行的操作受到一定限制，请详细了解授权。onInstall(e) 最常见的用法是直接调用 onOpen(e) 来添加自定义菜单。毕竟，安装插件后，文件已打开，因此除非重新打开文件，否则 onOpen(e) 不会自行运行。

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

当用户更改电子表格中任何单元格的值时，onEdit(e) 触发器会自动运行。大多数 onEdit(e) 触发器都会使用事件对象中的信息做出适当响应。例如，以下 onEdit(e) 函数会在单元格上设置一条注释，用于记录上次修改该单元格的时间。

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

当用户更改电子表格中的选择时，onSelectionChange(e) 触发器会自动运行。如需启用此触发器，您必须在添加触发器后以及每次打开电子表格时刷新电子表格。

如果选择在短时间内在多个单元格之间移动，系统可能会跳过一些选择更改事件以缩短延迟时间。例如，如果在两秒内进行了多次选择更改，则只有第一个和最后一个选择更改会激活 onSelectionChange(e) 触发器。

在以下示例中，如果选择一个空单元格，onSelectionChange(e) 函数会将该单元格的背景设置为红色。

/**
 * 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)和doPost(e)

当用户访问Web 应用或程序向 Web 应用发送 HTTP GET 请求时，doGet(e) 触发器会自动运行。当程序向 Web 应用发送 HTTP POST 请求时，doPost(e) 会运行。如需详细了解这些触发器，请参阅 Web 应用、HTML 服务和内容服务指南。请注意，doGet(e) 和 doPost(e) 不受上述限制。

可用的触发器类型

如果对简单触发器的限制导致它们无法满足您的需求，您可以改用可安装的触发器。下表总结了每种类型的事件支持哪些类型的触发器。例如，Google 表格、幻灯片、表单和文档都支持简单的打开触发器，但只有表格、文档和表单支持可安装的打开触发器。

事件	简单触发器	可安装的触发器
打开	function onOpen(e)
修改	function onEdit(e)
选择更改	function onSelectionChange(e)
安装	function onInstall(e)
更改
表单提交
基于时间（时钟）
Get	function doGet(e)
帖子	function doPost(e)

* Google 表单的“打开”事件不会在用户打开表单进行回复时触发，而是在编辑者打开表单进行修改时触发。