编辑器插件的触发器

Apps 脚本触发器会在每次发生指定事件时，触发指定的脚本函数（即触发器函数）。只有特定事件可以导致触发器触发，并且每个 Google Workspace 应用支持一组不同的事件。

当触发器触发时，系统会创建一个事件对象。此 JSON 结构包含有关已发生事件的详细信息。事件对象结构中的信息的组织方式因触发器类型而异。

创建事件对象后，Apps 脚本会将其作为参数传递给触发器函数。触发器函数是一个回调函数，您必须自行实现，以便执行任何适合响应事件的操作。例如，在编辑器插件中，触发器用于在文档打开时创建插件菜单项。在本例中，您可以实现 onOpen(e) 触发器函数来创建插件所需的菜单项，并可能需要使用事件对象中的数据。

本页面提供了有关在编辑器插件项目中使用触发器的指南。

编辑器插件触发器类型

您可以在编辑器插件中使用适用于 Apps 脚本项目的大多数通用触发器类型，包括简单触发器和大多数可安装的触发器。可用触发器类型的确切集合取决于要扩展的应用。

下表列出了编辑器插件可以使用的简单触发器和可安装触发器类型，并提供了指向相应事件对象的链接：

事件	事件对象	简单触发器	可安装的触发器
打开 系统会打开一个编辑器文件。	Docs onOpen 事件对象 表单 onOpen 事件对象 Google 表格 onOpen 事件对象 Movies onOpen 事件对象	文档 表单* 表格 幻灯片 function onOpen(e)	文档 表单 表格
安装 已安装插件。	onInstall 事件对象	文档 表单 表格 幻灯片 function onInstall(e)
修改 电子表格单元格的内容已更改。	表格 onEdit 事件对象	表格 function onEdit(e)	表格
更改 工作表中的内容被修改或设置了格式。	表格 onChange 事件对象		表格
表单提交 用户提交 Google 表单。	表单表单提交事件对象 Google 表格的表单提交事件对象		表单 表格
时间驱动（时钟） 触发器会按指定时间或间隔时间触发。	时间驱动的事件对象		文档 表单 表格 幻灯片

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

插件中的简单触发器

简单触发器使用一组预留的函数名称，不能使用需要授权的服务，并且会自动启用以供使用。在某些情况下，简单的触发器事件可以由可安装的触发器处理。

您只需实现使用以下预留名称之一的函数，即可向插件添加简单触发器：

• onOpen(e) 会在用户打开文档、电子表格或演示文稿时执行。onOpen(e) 也可以在编辑器中打开表单时执行（但在响应表单时不会执行）。此操作仅在用户有权修改相关文件的情况下执行，且最常用于创建菜单项。
• onInstall(e) 会在用户安装插件时执行。onInstall(e) 通常仅用于调用 onOpen(e)；这样可以确保插件菜单在安装后立即显示，而无需用户刷新页面。
• onEdit(e) 会在用户更改电子表格中的单元格值时执行。 在响应单元格移动、格式设置或其他不会更改单元格值的更改时，此触发器不会触发。

限制

插件中的简单触发器与其他类型的 Apps 脚本项目中的简单触发器受到相同的限制的约束。在设计插件时，请特别注意以下限制：

• 如果文件以只读（查看或注释）模式打开，简单触发器不会运行。此行为会阻止系统填充您的插件菜单。
• 在某些情况下，编辑器插件会在无授权模式下运行其 onOpen(e) 和 onEdit(e) 简单触发器。此模式会产生一些额外的复杂功能，如插件授权模型中所述。
• 简单触发器不能使用服务或执行其他需要授权的操作，但插件授权模型中所述的操作除外。
• 简单触发器的运行时间不能超过 30 秒。请注意尽可能减少在简单触发器函数中完成的处理量。
• 简单触发器受 Apps 脚本触发器配额限制的约束。

插件中的可安装触发器

插件可以使用 Apps 脚本 Script 服务以编程方式创建和修改可安装的触发器。您无法手动创建插件可安装的触发器。与简单触发器不同，可安装触发器可以使用需要授权的服务。

插件中的可安装触发器在遇到错误时不会向用户发送错误消息，因为在大多数情况下，用户无法解决问题。因此，您应该将插件设计为尽可能代表用户妥善处理错误。

插件可以使用以下可安装触发器：

• “Open”可安装触发器会在用户打开文档或电子表格时或在编辑器中打开表单时执行（但响应表单时不会执行）。
• 当用户更改电子表格中的单元格值时，系统会执行修改可安装触发器。当格式设置或其他更改不改变单元格的值时，此触发器不会触发。
• 用户在电子表格中进行任何更改，包括对电子表格本身进行格式设置和修改（例如添加行）时，就会执行“更改”可安装触发器。

• “表单提交”可安装触发器会在用户提交 Google 表单回复时执行。

• 时间驱动的触发器（也称为时钟触发器）在特定时间或按固定时间间隔重复触发。

为可安装触发器授权

通常，如果开发者更新插件以使用需要额外授权的新服务，则当用户下次使用插件时，系统会提示用户重新授权。

不过，使用触发器的插件会遇到特殊的授权验证。假设有一个插件，它使用触发器监控表单提交情况：表单创建者可能会在首次使用时对该插件进行授权，然后让其运行数月或数年，甚至无需重新打开表单。如果插件开发者要更新插件以使用需要额外授权的新服务，表单创建者将永远不会看到重新授权对话框，因为他们从未重新打开过表单，因而插件也将停止运行。

与常规 Apps 脚本项目中的触发器不同，插件中的触发器仍会触发，即使需要重新授权也是如此。但是，如果脚本遇到需要授权的代码行，但该脚本所不具备，则仍然会失败。为避免这种情况，开发者可以使用 ScriptApp.getAuthorizationInfo() 方法控制对在插件发布版本之间发生更改的部分代码的访问。

以下是建议在触发器函数中使用的结构示例，以避免授权问题。示例触发器函数会响应 Google 表格插件中的表单提交事件，如果需要重新授权，它会使用模板化 HTML 向插件的用户发送提醒电子邮件。

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

限制

插件中的可安装触发器也受到管理其他类型的 Apps 脚本项目中的可安装触发器的相同限制。

除了这些限制之外，插件中的可安装触发器还有一些限制：

• 对于每个用户的每个文档，每个插件只能有一个每种类型的触发器。 例如，在给定的电子表格中，该用户只能有一个修改触发器，不过也可以在同一个电子表格中有一个表单提交触发器或时间驱动型触发器。有权访问同一电子表格的不同用户可以有自己的一组单独的触发器。
• 插件只能为使用该插件的文件创建触发器。 也就是说，Google 文档 A 中使用的插件无法创建触发器来监控 Google 文档 B 何时打开。
• 时间驱动型触发器的运行频率不能超过每小时一次。
• 当可安装的触发器运行的代码抛出异常时，插件不会自动向用户发送电子邮件。开发者应负责妥善检查和处理失败情况。
• 插件触发器会在出现以下任何情况时停止触发：
  • 如果用户卸载了该插件，
  • 如果插件在文档中被停用（如果重新启用，触发器将再次运行），或者
  • 开发者取消发布该插件或向插件商店提交损坏的版本。
• 插件触发器函数会一直执行，直到调用到使用未经授权的服务的代码，并停止运行。只有当插件已发布时，情况才会如此；常规 Apps 脚本项目或未发布的插件中的同一触发器如果脚本的任何部分需要授权，则根本不会执行。
• 可安装触发器需遵循 Apps 脚本触发器配额限制。