编辑器插件的触发器

Apps 脚本触发器会在每次发生指定事件时执行指定的脚本函数（触发器函数）。只有特定事件才能触发触发器，并且每款 Google Workspace 应用支持的事件各不相同。

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

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

本页介绍了在编辑器插件项目中使用触发器的指南。

编辑器插件触发器类型

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

注意 ：与编辑器插件不同，Google Workspace 插件目前无法使用通用 Apps 脚本简单触发器或可安装触发器。而是使用专为 Google Workspace 插件设计的触发器。如需了解详情，请参阅 Google Workspace 插件触发器。

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

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

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

插件中的简单触发器

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

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

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

限制

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

• 如果文件以只读（查看或评论）模式打开，简单触发器不会运行。此行为会导致您的插件菜单无法填充。
• 在某些情况下，编辑器插件会在无授权模式下运行其 onOpen(e) 和 onEdit(e) 简单触发器。此模式会带来一些额外的复杂性，如插件授权模型中所述。
• 简单触发器无法使用服务或执行需要授权的其他操作，但插件授权模型中所述的操作除外。
• 简单触发器的运行时长不得超过 30 秒。请务必尽量减少在简单的触发器函数中执行的处理量。
• 简单触发器受 Apps 脚本触发器配额限制的约束。

插件中的可安装触发器

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

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

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

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

• 在有 Google 表单回复被提交时，表单提交可安装的触发器会执行。

  注意 ：表单提交触发器有两个版本，一个适用于 Google 表格（用于收集表单回复），另一个适用于 Google 表单。传递给 Google 表格表单提交触发器函数的事件对象更简单，并会以简单的数组形式返回响应值。传递给 Google 表单表单提交触发器函数的事件对象会提供更多信息，这些信息包含在 FormResponse 对象中。

• 基于时间的触发器（也称为时钟触发器）会在特定时间触发，或按固定的时间间隔重复触发。

授权可安装的触发器

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

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

与常规 Apps 脚本项目中的触发器不同，即使需要重新授权，插件中的触发器也会继续触发。不过，如果脚本遇到需要脚本不具备的授权的一行代码，脚本仍会失败。为避免这种情况，开发者可以使用 ScriptApp.getAuthorizationInfo() 方法来控制对已发布插件版本之间发生变化的代码部分的访问权限。

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

Code.gs

triggers/form/Code.gs

在 GitHub 上查看

/**
 * 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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

在 GitHub 上查看

<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 Script 项目中的可安装触发器相同的限制。

除了这些限制之外，插件中的可安装触发器还存在以下几项限制：

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