简单触发器

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

如需了解如何在 Google Workspace 插件 项目中使用触发器，请参阅 Google Workspace 插件的触发器。

使用入门

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

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

上述函数名称中的 e 参数是传递给函数的 事件对象。该对象包含有关导致触发器触发的上下文的信息，但使用它是可选的。

限制

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

• 脚本必须绑定到 Google 表格、幻灯片、文档或 表单文件，否则必须是 扩展其中一个应用的插件 。
• 如果文件在只读（查看或评论）模式下打开，则不会运行。
• 脚本执行和 API 请求不会导致触发器运行。例如， 调用 Range.setValue() 来修改单元格不会导致电子表格的 onEdit 触发器运行。
• 它们无法访问需要 授权的服务。例如， 简单触发器无法发送电子邮件，因为 Gmail 服务需要 授权，但简单触发器可以使用 Language 服务翻译短语，该服务是匿名的。
• 它们可以修改所绑定的文件，但无法访问其他文件，因为这需要授权。
• 它们可能能够确定当前用户的身份，也可能无法确定， 具体取决于一组 复杂的安全限制。
• 它们无法运行超过 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)

onInstall(e) 触发器会在用户在 Google 文档、表格、幻灯片或 表单中安装 编辑器插件时自动运行。当用户 从 Google Workspace Marketplace 网站安装插件时，该触发器不会运行。 onInstall(e) 最常见的用途是调用 onOpen(e) 以添加自定义菜单。安装插件后，文件已打开，因此除非重新打开文件，否则 onOpen(e) 不会自行运行。 请注意，onInstall(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()}`);
}

onEdit() 触发器最多只能将 2 个触发器事件排入队列。

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 服务和 Content 服务指南中，对这些触发器进行了更详细的演示。请注意，doGet(e) 和 doPost(e) 不受上述限制的约束。

可用触发器类型

如果简单触发器的限制使其无法满足 您的需求，则可安装的触发器 可能会有所帮助。下表总结了每种事件可用的触发器类型。例如，Google 表格、幻灯片、表单和文档都支持简单的打开触发器，但只有表格、文档和表单支持可安装的打开触发器。

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

Google 表单的打开事件不会在用户打开表单进行回复时发生，而是在编辑器打开表单进行修改时发生。