此页面由 Cloud Translation API 翻译。

编辑器插件的触发器

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

当触发器触发时，系统会创建一个事件对象。此 JSON 结构包含有关所发生事件的详细信息。事件对象结构中的信息会根据触发器类型以不同的方式进行整理。

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

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

编辑器插件触发器类型

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

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

事件	事件对象	简单触发器	可安装的触发器
打开系统会打开一个编辑器文件。	Google 文档 onOpen 事件对象 Google 表单 onOpen 事件对象 Google 表格 onOpen 事件对象 Google 幻灯片 onOpen 事件对象	文档表单* 表格幻灯片 `function onOpen(e)`	文档表单表格
安装插件已安装。	onInstall 事件对象	文档表单表格幻灯片 `function onInstall(e)`
修改电子表格单元格内容已更改。	Google 表格 onEdit 事件对象	Google 表格 `function onEdit(e)`	Google 表格
更改工作表中的内容已编辑或设置了格式。	Google 表格 onChange 事件对象		Google 表格
form-submit 已提交 Google 表单。	表单的 form-submit 事件对象工作表的 form-submit 事件对象		表单表格
时间驱动（时钟）触发器在指定时间或间隔触发。	时间驱动的事件对象		Google 文档 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