简单触发器

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

使用入门

如需使用简单的触发器,只需创建一个使用以下其中一个函数名称的函数:

  • onOpen(e) 会在用户打开用户有权编辑的电子表格、文档、演示文稿或表单时运行。
  • 当用户从 Google 文档、表格、幻灯片或表单中安装 Editor 插件时,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 表格、幻灯片、文档或表单添加自定义菜单项

触发器/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)

当用户从 Google 文档、表格、幻灯片或表单中安装 Editor 插件时,onInstall(e) 触发器会自动运行。当用户从 Google Workspace Marketplace 网站安装插件时,触发器不会运行。请注意,onInstall(e) 的功能存在某些限制,请详细了解授权onInstall(e) 的最常见用途是调用 onOpen(e) 添加自定义菜单。毕竟,安装插件后,文件已经打开,因此除非文件重新打开,否则 onOpen(e) 不会单独运行。

触发器/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)

当用户更改电子表格中任意单元格的值时,onEdit(e) 触发器会自动运行。大多数 onEdit(e) 触发器使用事件对象中的信息进行适当响应。例如,以下 onEdit(e) 函数对单元格设置了一条注释,记录上一次修改内容。

触发器/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());
}

onSelectionChange(e)

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

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

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

触发器/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)doPost(e)

当用户访问 Web 应用或程序向 Web 应用发送 HTTP GET 请求时,doGet(e) 触发器会自动运行。doPost(e) 在程序向 Web 应用发送 HTTP POST 请求时,doPost(e) 触发器会运行。请注意,doGet(e)doPost(e) 不受上述限制。

可用的触发器类型

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

事件 简单触发器 可安装的触发器
打开
表格
幻灯片
表单*
文档

function onOpen(e)

表格
表单*
文档
修改
表格

function onEdit(e)

表格
选择变更
表格

function onSelectionChange(e)

安装
表格
幻灯片
表单
文档

function onInstall(e)

换乘
表格
表单提交
表格
表单
时间驱动(时钟)
表格
幻灯片
表单
文档
协作平台
独立
获取
协作平台
独立

function doGet(e)

帖子
协作平台
独立

function doPost(e)

* Google 表单的开放事件不会在用户打开表单进行回复时发生,而是在编辑者打开表单进行编辑时发生。