Apps 脚本触发器触发指定的脚本 函数(即触发器函数),每当有指定事件发生时,系统即会执行该函数(即触发器函数) 。只有特定事件会触发触发器,每个 Google Workspace 应用支持一组不同的事件。
当触发器触发时,系统会创建一个事件对象。此 JSON 结构 包含发生的事件的详细信息。事件中的信息 对象结构的组织方式因触发器类型而异。
创建事件对象后,Apps 脚本会将其作为参数传递给
触发函数。触发器函数是一个回调函数,您必须
实施您自己的解决方案,以采取任何适当的措施来应对
事件。例如,在编辑器插件中,
用于在文档打开时创建插件菜单项。在这种情况下,
在 onOpen(e)
触发器函数上实现用于创建插件的菜单项
可能需要使用事件对象中的数据。
本页面介绍了如何在 编辑者 插件项目。
编辑器插件触发器类型
您可以使用 Apps 脚本项目可用的大多数通用触发器类型 使用编辑器插件,包括简单触发器 和大多数可安装的触发器。通过 可用的触发器类型的具体集合取决于要扩展的应用。
下表显示了哪些类型的简单和可安装触发器, 编辑器插件可以使用并提供指向相应事件对象的链接:
事件 | 事件对象 | 简单触发器 | 可安装触发器 |
---|---|---|---|
打开 系统会打开一个编辑器文件。 |
<ph type="x-smartling-placeholder"></ph>
文档 onOpen 事件对象 表单 onOpen 事件对象 Google 表格 onOpen 事件对象 Google 幻灯片 onOpen 事件对象 |
文档 表单* 表格 幻灯片
|
文档 表单 表格 |
安装 已安装该插件。 |
<ph type="x-smartling-placeholder"></ph> onInstall 事件对象 |
文档 表单 表格 幻灯片
|
|
编辑 电子表格单元格内容已更改。 |
<ph type="x-smartling-placeholder"></ph> Google 表格 onEdit 事件对象 |
表格
|
表格 |
更改 工作表中的内容已修改或设置了格式。 |
<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
authorizationemail.html
限制
插件中的可安装触发器需要遵守 限制 来管理其他类型的 Apps 脚本项目中的可安装触发器。
除了这些限制外,可安装 触发器,具体如下:
- 对于每位用户的每个文档,每个插件只能有一个针对每种类型的触发器。 例如,在给定的电子表格中,一位用户只能进行一次修改 触发器,尽管用户可能还有表单提交触发器或 时间驱动型触发器。拥有访问权限的其他用户 可以分别创建一组触发器。
- 插件只能为使用该插件的文件创建触发器。 也就是说,Google 文档 A 中使用的插件无法创建 监控 Google 文档 B 的打开时间。
- 时间驱动型触发器的运行频率不能超过每小时一次。
- 当代码由 则会抛出异常。由开发者负责检查 并妥善处理故障情况
- 插件触发器会在以下任一情况下停止触发:
<ph type="x-smartling-placeholder">
- </ph>
- 如果用户卸载了该插件
- 如果插件在文档中停用(如果重新启用了该插件,则触发器 恢复运行),或者
- 如果开发者取消发布该插件或将已损坏的版本提交到 插件商店。
- 插件触发器函数会一直执行,直到到达 便会停止运行只有当 该插件已发布;常规 Apps 脚本项目中的同一个触发器,或者 如果某个未发布的插件需要脚本的任何部分, 授权。
- 可安装的触发器受 Apps 脚本触发器的约束 配额限制。