编辑器插件的触发器

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 脚本触发器的约束 配额限制