可安装触发器

与简单触发器类似，可安装的触发器可让 Apps 脚本在发生特定事件（例如打开文档）时自动运行函数。不过，可安装的触发器比简单触发器更灵活：它们可以调用需要授权的服务，提供多种其他类型的事件（包括时间驱动型 [时钟] 触发器），并且可以通过编程方式进行控制。对于简单触发器和可安装的触发器，Apps 脚本都会向触发的函数传递一个事件对象，其中包含有关事件发生时所处上下文的信息。

注意： 如需详细了解如何在插件中使用触发器，请参阅 Google Workspace 插件的触发器。

限制

虽然可安装的触发器比简单触发器更灵活，但仍受以下几项限制：

• 如果文件以只读（查看或评论）模式打开，这些脚本不会运行。对于独立脚本，用户至少需要拥有脚本文件的查看权限，触发器才能正常运行。

• 脚本执行和 API 请求不会导致触发器运行。例如，调用 FormResponse.submit() 以提交新的表单响应不会导致表单的提交触发器运行。

  注意： 此限制的例外情况是 Form.submitGrades()。如果您的代码使用 onFormSubmit 触发器，则调用 Form.submitGrades() 会触发 onFormSubmit 条件，并导致无限循环。为防止出现无限循环，请在调用 submitGrades() 之前添加用于检查成绩是否已存在的代码。

• 可安装的触发器始终在创建者的账号下运行。例如，如果您创建可安装的打开触发器，当您的同事打开文档时（如果您的同事具有修改权限），该触发器会运行，但会以您的账号运行。这意味着，如果您创建了一个触发器，用于在文档打开时发送电子邮件，则电子邮件始终会从您的账号发送，而不一定是从打开文档的账号发送。不过，您可以为每个账号创建一个可安装的触发器，这样每个账号都会发送一封电子邮件。

• 指定账号无法看到从第二个账号安装的触发器，即使第一个账号仍可激活这些触发器。

• 可安装的触发器受 Apps 脚本触发器配额限制的约束。

时间驱动型触发器

时间驱动型触发器（也称为时钟触发器）类似于 Unix 中的 cron 作业。通过定时触发器，脚本可以在特定时间或按周期性间隔执行，频率可以高达每分钟一次，也可以低至每月一次。（请注意，插件最多每小时可以使用一次定时触发器。）时间可能会略有随机性 - 例如，如果您创建了上午 9 点的周期性触发器，Apps 脚本会选择上午 9 点到 10 点之间的时间，然后每天保持该时间一致，以便在触发器再次触发之前经过 24 小时。

事件驱动型触发器

可安装的事件驱动型触发器在概念上与 简单触发器（如 onOpen()）类似，但它们可以响应其他事件，并且行为方式也不同。

例如，Google 表格的可安装的打开触发器会在任何具有修改权限的用户打开该电子表格时激活，就像简单的 onOpen() 触发器一样。不过，可安装的版本可以调用需要授权的服务。可安装的版本会以创建触发器的用户的授权运行，即使具有修改权限的其他用户打开电子表格也是如此。

Google Workspace 应用有多种可安装的触发器：

• 当用户打开有权修改的电子表格、文档或表单时，可安装的打开触发器会运行。
• 当用户修改电子表格中的值时，可安装的修改触发器会运行。
• 当用户修改电子表格本身的结构时（例如，通过添加新工作表或移除列），可安装的更改触发器会运行。
• 当用户回复表单时，可安装的表单提交触发器会运行。 表单提交触发器有两个版本，一个用于 Google 表单本身，另一个用于表单提交到电子表格时。
• 当用户的日历活动更新（创建、修改或删除）时，可安装的日历活动触发器会运行。

您可以在独立脚本和绑定脚本中使用可安装的触发器。例如，独立脚本可以通过调用 TriggerBuilder.forSpreadsheet(key) 并传入电子表格的 ID，以编程方式为任意 Google 表格文件创建可安装的触发器。

手动管理触发器

如需在脚本编辑器中手动创建可安装的触发器，请按以下步骤操作：

1. 打开您的 Apps 脚本项目。
2. 点击左侧的触发器图标 。
3. 点击右下角的添加触发器。
4. 选择并配置要创建的触发器类型。
5. 点击保存。

以编程方式管理触发器

您还可以使用 Script 服务以编程方式创建和删除触发器。首先调用 ScriptApp.newTrigger(functionName)，该方法会返回一个 TriggerBuilder。

以下示例展示了如何创建两个定时触发器：一个每 6 小时触发一次，另一个每周一上午 9 点（在脚本设置的时区中）触发一次。

triggers/triggers.gs

在 GitHub 上查看

/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

以下示例展示了如何为电子表格创建可安装的打开触发器。请注意，与简单的 onOpen() 触发器不同，可安装触发器的脚本不需要绑定到电子表格。如需从独立脚本创建此触发器，只需将 SpreadsheetApp.getActive() 替换为对 SpreadsheetApp.openById(id) 的调用即可。

triggers/triggers.gs

在 GitHub 上查看

/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

如需以编程方式修改现有的可安装触发器，您必须删除该触发器并创建一个新触发器。如果您之前存储了触发器的 ID，可以通过将该 ID 作为实参传递给以下函数来删除它。

triggers/triggers.gs

在 GitHub 上查看

/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

在创建触发器之前，我们建议您验证关联的函数是否具有所有必需的 OAuth 权限。

触发器中的错误

当可安装的触发器触发但函数抛出异常或无法成功运行时，您不会在屏幕上看到错误消息。毕竟，当定时触发器运行或另一用户激活表单提交触发器时，您可能不在电脑旁。

而是会向您发送如下电子邮件：

From: [e-mail]
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

该电子邮件会包含一个用于停用或重新配置触发器的链接。如果脚本绑定到 Google 表格、文档或表单文件，电子邮件还会包含指向该文件的链接。通过这些链接，您可以停用触发器或修改脚本来修复 bug。

注意： 由插件创建的可安装触发器不会向用户发送这些电子邮件通知。

如需查看与您的 Google 账号关联的所有触发器并停用不再需要的触发器，请按以下步骤操作：

1. 前往 script.google.com。
2. 点击左侧的我的触发器。

3. 如需删除触发器，请点击触发器右侧的“更多”图标 > 删除触发器。

   注意： 无法在此页面上停用 onOpen() 等简单触发器；您必须修改相应脚本，然后移除或重命名 onOpen() 函数。

插件中的触发器

除了可安装的触发器，您还可以在插件中使用清单触发器。如需了解详情，请参阅 Google Workspace 插件的触发器。