当特定事件(如打开文档)发生时,触发器可让 Apps 脚本自动运行函数。简单触发器是内置于 Apps 脚本中的一组预留函数,如 onOpen(e)
函数,当用户打开 Google 文档、表格、幻灯片或表单文件时执行。
可安装触发器提供的功能比简单触发器多,但必须在使用前启用。对于这两种类型的触发器,Apps 脚本会向触发的函数传递事件对象,其中包含事件发生时所处的上下文的相关信息。
使用入门
如需使用简单的触发器,只需创建一个使用以下某个预留函数名称的函数:
onOpen(e)
在用户打开用户有权编辑的电子表格、文档、演示文稿或表单时运行。- 当用户从 Google 文档、表格、幻灯片或表单中安装编辑器插件时,系统会运行
onInstall(e)
。 onEdit(e)
会在用户更改电子表格中的值时运行。- 用户在电子表格中更改选择时,系统会运行
onSelectionChange(e)
。 - 当用户访问 Web 应用或程序向 Web 应用发送 HTTP
GET
请求时,doGet(e)
会运行。 - 当程序向 Web 应用发送 HTTP
POST
请求时,doPost(e)
会运行。
上述函数名称中的 e
参数是传递给该函数的事件对象。该对象包含有关导致触发器触发的上下文的信息,但可以选择使用该对象。
限制
由于简单触发器会自动触发,而不会要求用户授权,因此会受几项限制:
- 该脚本必须绑定到 Google 表格、幻灯片、文档或表单文件,或者是扩展其中一个应用的插件。
- 如果某个文件以只读(查看或评论)模式打开,则系统不会运行这些文件。
- 脚本执行和 API 请求不会导致触发器运行。例如,调用
Range.setValue()
来修改单元格不会导致电子表格的onEdit
触发器运行。 - 它们无法访问需要授权的服务。例如,简单的触发器无法发送电子邮件,因为 Gmail 服务需要授权,而简单的触发器可以使用语言服务(匿名)转换短语。
- 用户可以修改所绑定的文件,但无法访问其他文件,因为这需要获得授权。
- 用户不一定能确定当前用户的身份,具体取决于一组复杂的安全限制。
- 它们的运行时长不能超过 30 秒。
- 在某些情况下,编辑器插件会在无授权模式下运行
onOpen(e)
和onEdit(e)
简单触发器,这会带来一些额外的复杂功能。如需了解详情,请参阅插件授权生命周期指南。 - 简单的触发器受 Apps 脚本触发器配额限制的约束。
这些限制不适用于 doGet(e)
或 doPost(e)
。
onOpen(e)
当用户打开他们有权编辑的电子表格、文档、演示文稿或表单时,onOpen(e)
触发器会自动运行。(触发器在响应表单时不会运行,仅在打开表单以进行修改时才会运行)。onOpen(e)
最常用于向 Google 表格、幻灯片、文档或表单添加自定义菜单项。
onInstall(e)
当用户从 Google 文档、表格、幻灯片或表单中安装编辑器插件时,onInstall(e)
触发器会自动运行。当用户从 Google Workspace Marketplace 网站安装插件时,触发器将不会运行。请注意,onInstall(e)
可以执行的操作存在一些限制,请详细了解授权。最常见的 onInstall(e)
用途是调用 onOpen(e)
以添加自定义菜单。毕竟,安装插件后,该文件已经打开,因此,除非重新打开该文件,否则 onOpen(e)
不会自行运行。
onEdit(e)
当用户更改电子表格中任意单元格的值时,onEdit(e)
触发器会自动运行。大多数 onEdit(e)
触发器使用事件对象中的信息进行适当的响应。例如,以下 onEdit(e)
函数针对单元格设置了一条评论,用于记录上次编辑。
onSelectionChange(e)
当用户更改电子表格中的选择时,onSelectionChange(e)
触发器会自动运行。要启用此触发器,您必须在添加触发器后以及每次打开电子表格时刷新电子表格。
如果选择在短时间内在多个单元格之间移动,系统可能会跳过某些选择更改事件以减少延迟。例如,如果在两秒内做出多项选择更改,则只有第一次和最后一项选择更改才会激活 onSelectionChange(e)
触发器。
在下面的示例中,如果选择空白单元格,则 onSelectionChange(e)
函数会将单元格的背景设置为红色。
doGet(e)
和doPost(e)
当用户访问 Web 应用或程序向 Web 应用发送 HTTP GET
请求时,doGet(e)
触发器会自动运行。当程序向 Web 应用发送 HTTP POST
请求时,doPost(e)
触发器会运行。如需详细了解这些触发器,请参阅 Web 应用、HTML 服务和内容服务指南。请注意,doGet(e)
和 doPost(e)
不受上述限制。
可用的触发器类型
如果简单的触发器存在一些限制,导致这些触发器无法满足您的需求,不妨改用可安装的触发器。下表总结了每类事件可用的触发器类型。例如,Google 表格、幻灯片、表单和文档都支持简单的打开触发器,但只有表格、文档和表单支持可安装的打开触发器。
事件 | 简单触发器 | 可安装的触发器 |
---|---|---|
打开 |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
修改 |
![]()
|
![]() |
选择变更 |
![]()
|
|
安装 |
![]() ![]() ![]() ![]()
|
|
换乘 |
![]() |
|
表单提交 |
![]() ![]() |
|
时间驱动(时钟) |
![]() ![]() ![]() ![]() ![]() ![]() |
|
获取 |
![]() ![]()
|
|
帖子 |
![]() ![]()
|
* Google 表单的打开事件不会出现在用户打开要回复的表单时,而是由编辑器打开表单进行修改。