编辑器插件的触发器

Apps 脚本触发器触发指定的脚本 函数（即触发器函数），每当有指定事件发生时，系统即会执行该函数（即触发器函数） 。只有特定事件会触发触发器，每个 Google Workspace 应用支持一组不同的事件。

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

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

本页面介绍了如何在 编辑者 插件项目。

编辑器插件触发器类型

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

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

事件 事件对象 简单触发器 可安装触发器
打开
系统会打开一个编辑器文件。		 <ph type="x-smartling-placeholder"></ph> 文档 onOpen 事件对象
表单 onOpen 事件对象
Google 表格 onOpen 事件对象
Google 幻灯片 onOpen 事件对象 		文档
表单*
表格
幻灯片

function onOpen(e)

 文档
表单
表格
安装
已安装该插件。		 <ph type="x-smartling-placeholder"></ph> onInstall 事件对象 文档
表单
表格
幻灯片

function onInstall(e)
编辑
电子表格单元格内容已更改。		 <ph type="x-smartling-placeholder"></ph> Google 表格 onEdit 事件对象 表格

function onEdit(e)

 表格
更改
工作表中的内容已修改或设置了格式。		 <ph type="x-smartling-placeholder"></ph> Google 表格 onChange 事件对象 表格
表单-提交
系统会提交一个 Google 表单。		 <ph type="x-smartling-placeholder"></ph> 表单表单提交事件对象
Google 表格的表单提交事件对象 		表单
表格
时间驱动（时钟）
触发器会在指定的时间或间隔触发。		 <ph type="x-smartling-placeholder"></ph> 时间驱动的事件对象 文档
表单
表格
幻灯片

* 当用户打开 而是在编辑者打开表单进行修改时进行。

插件中的简单触发器

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

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

  • onOpen(e) 会在用户打开文档、电子表格或 演示文稿。在编辑器中打开表单时，系统也会执行 onOpen(e) （但在回复表单时不行）。该函数仅在用户 拥有相关文件的编辑权限，通常用于创建 菜单项。
  • onInstall(e) 会在用户安装插件时执行。一般价格：onInstall(e) 仅用于调用 onOpen(e)；这样可确保附加菜单 安装后立即启动，而无需用户刷新页面。
  • 当用户更改电子表格中的单元格值时，系统会执行 onEdit(e)。 此触发器不会在响应单元格移动、格式设置或 其他不改变单元格值的更改

限制

插件中的简单触发器也要遵守相同的规则 限制以管理简单的 触发器。请特别注意 设计插件时的一些限制：

  • 如果文件以只读模式（查看或 评论模式）。此行为可防止系统填充您的插件菜单。
  • 在某些情况下，编辑器插件会运行其 onOpen(e)， 无授权模式下的 onEdit(e) 简单触发器。这种模式会展示 一些额外的复杂问题， 附加授权模式。
  • 简单触发器无法使用服务，也无法接受 需要执行的其他操作 授权，除非是 概述的 附加授权模式。
  • 简单触发器的运行时长不能超过 30 秒。注意尽量减少 在简单的触发器函数中完成的处理量。
  • 简单触发器受 Apps 脚本触发器的约束 配额限制。

插件中的可安装触发器

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

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

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

  • Open 可安装触发器在用户打开文档时执行， 或是在编辑器中打开某个表单时（但在回复时无法 表单）。
  • 修改可安装触发器会在用户在 电子表格。此触发器不会在响应格式设置或其他错误响应时触发 不会改变单元格的值。
  • 更改可安装触发器会在用户在 包括对电子表格的格式修改和对电子表格的修改 （例如添加行）。

  • 表单提交可安装触发器会在收到 Google 表单回复时执行 提交。

  • 时间驱动型触发器 （也称为时钟触发器）可在特定时间触发，或在特定时间 固定时间间隔。

为可安装的触发器授权

通常，如果开发者更新插件以使用需要 额外授权，系统会提示用户重新为该插件授权 每次使用时都会用到。

但是，使用触发器的插件会遇到特殊的授权验证问题。 假设某个插件使用触发器监控表单提交情况：表单 创作者可以在第一次使用该插件时授权， 可以连续数月或数年运行，甚至不需要重新打开此表单。 如果插件开发者要更新该插件，以便使用 需要额外的授权，表单创建者永远不会看到 重新授权对话框，因为他们从未重新打开该表单， 就会停止运行

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

下面是推荐在触发器函数中使用的结构示例， 避免授权问题示例触发器函数响应 事件，并且如果重新授权 使用模板化 HTML 向该插件的用户发送一封提醒电子邮件。

Code.gs

triggers/form/Code.gs
/**
 * 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
<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 的打开时间。
  • 时间驱动型触发器的运行频率不能超过每小时一次。
  • 当代码由 则会抛出异常。由开发者负责检查 并妥善处理故障情况
  • 插件触发器会在以下任一情况下停止触发： <ph type="x-smartling-placeholder">
      </ph>
    • 如果用户卸载了该插件
    • 如果插件在文档中停用（如果重新启用了该插件，则触发器 恢复运行），或者
    • 如果开发者取消发布该插件或将已损坏的版本提交到 插件商店。
  • 插件触发器函数会一直执行，直到到达 便会停止运行只有当 该插件已发布；常规 Apps 脚本项目中的同一个触发器，或者 如果某个未发布的插件需要脚本的任何部分， 授权。
  • 可安装的触发器受 Apps 脚本触发器的约束 配额限制。