借助简单触发器和可安装的触发器,您可以让 Apps 脚本在发生特定事件时自动运行函数。触发器触发时,Apps 脚本会将事件对象作为参数传递给函数,通常称为 e
。事件对象包含有关导致触发器触发的上下文的信息。例如,以下示例代码展示了 Google 表格脚本的简单 onEdit(e)
触发器,该触发器使用事件对象来确定被修改的是哪个单元格。
function onEdit(e){
// Set a comment on the edited cell to indicate when it was changed.
var range = e.range;
range.setNote('Last modified: ' + new Date());
}
本页详细介绍了不同类型触发器的事件对象中的字段。
Google 表格事件
借助各种 Google 表格专用触发器,脚本可以响应用户在电子表格中的操作。
打开(简单且可安装) |
|
---|---|
authMode |
LIMITED |
source |
一个 Spreadsheet |
triggerUid |
触发此事件的触发器的 ID(仅限可安装的触发器)。 4034124084959907503 |
user |
一个 amin@example.com |
更改(可安装) |
|
---|---|
authMode |
FULL |
changeType |
更改类型( INSERT_ROW |
source |
一个
Spreadsheet |
triggerUid |
触发此事件的触发器的 ID。 4034124084959907503 |
user |
一个 amin@example.com |
修改(简单且可安装) |
|
---|---|
authMode |
LIMITED |
oldValue |
修改前的单元格值(如果有)。仅当所修改的范围为单个单元格时才可用。如果单元格之前没有内容,则为未定义。 1234 |
range |
一个 Range |
source |
一个 Spreadsheet |
triggerUid |
触发此事件的触发器的 ID(仅限可安装的触发器)。 4034124084959907503 |
user |
一个 amin@example.com |
value |
修改后的新单元格值。仅当所修改的范围为单个单元格时才可用。 10 |
表单提交(可安装) |
|
---|---|
authMode |
FULL |
namedValues |
一个对象,其中包含表单提交中的题目名称和值。 { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] } |
range |
一个 Range |
triggerUid |
触发此事件的触发器的 ID。 4034124084959907503 |
values |
数组,其中值的顺序与电子表格中显示的顺序相同。 ['2015/05/04 15:00', 'amin@example.com', 'Bob', '27', 'Bill', '28', 'Susan', '25'] |
Google 文档事件
借助触发器,Google 文档可以在用户打开文档时做出响应。
打开(简单且可安装) |
|
---|---|
authMode |
LIMITED |
source |
一个 Document |
triggerUid |
触发此事件的触发器的 ID(仅限可安装的触发器)。 4034124084959907503 |
user |
一个 amin@example.com |
Google 幻灯片事件
借助触发器,Google 幻灯片可以在用户打开演示文稿时做出响应。
打开(简单) |
|
---|---|
authMode |
LIMITED |
source |
一个 Presentation |
user |
一个 amin@example.com |
Google 表单事件
借助 Google 表单专用触发器,您可以让脚本在用户修改表单或提交回复时做出响应。
打开*(简单且可安装) |
|
---|---|
authMode |
LIMITED |
source |
一个 Form |
triggerUid |
触发此事件的触发器的 ID(仅限可安装的触发器)。 4034124084959907503 |
user |
一个 amin@example.com |
* 此事件不会在用户打开表单进行回复时发生,而是在编辑者打开表单进行修改时发生。
表单提交(可安装) |
|
---|---|
authMode |
FULL |
response |
一个 FormResponse |
source |
一个 Form |
triggerUid |
触发此事件的触发器的 ID。 4034124084959907503 |
Google 日历活动
当用户的日历活动发生更新(创建、修改或删除)时,日历触发器会触发。
这些触发器不会告知您哪个事件发生了变化或发生了怎样的变化。相反,它们表示您的代码需要执行增量同步操作,才能获取日历的近期更改。如需详细了解此过程,请参阅 Calendar API 的同步资源指南。
如需在 Apps 脚本中与 Google 日历同步,请执行以下步骤:
- 为脚本项目启用 Google 日历高级服务。内置的 Calendar 服务不足以满足此工作流程的要求。
- 确定应同步哪些日历。对于每种此类日历,请使用日历高级服务的 Events.list() 方法执行初始同步操作。
- 初始同步的结果会为该日历返回
nextSyncToken
。存储此令牌以备日后使用。 - 当 Apps Script
EventUpdated
触发器触发,表示日历事件发生更改时,使用存储的nextSyncToken
对受影响的日历执行增量同步。这实际上是另一个 Events.list() 请求,但提供nextSyncToken
会将响应限制为仅包含自上次同步以来发生变化的事件。 - 检查同步的响应,了解哪些事件已更新,并让代码做出适当的响应。例如,您可以记录更改、更新电子表格、发送电子邮件通知或执行其他操作。
- 使用增量同步请求返回的
nextSyncToken
更新您为该日历存储的nextSyncToken
。这会强制下一次同步操作仅返回最新的更改。
EventUpdated(可安装) |
|
---|---|
authMode |
FULL |
calendarId |
发生事件更新的日历的字符串 ID。 susan@example.com |
triggerUid |
触发此事件的触发器的 ID。 4034124084959907503 |
Google Workspace 插件事件
当用户安装插件时,系统会自动运行 onInstall()
触发器。
安装(简单) |
|
---|---|
authMode |
FULL |
Google Chat 应用事件
如需了解 Google Chat 中的事件对象,请参阅接收和响应与 Google Chat 应用的互动。
基于时间的事件
借助基于时间的触发器(也称为时钟触发器),您可以让脚本在特定时间或按重复间隔执行。
基于时间(可安装) | |
---|---|
authMode |
FULL |
day-of-month |
介于 由于此属性名称包含短划线,因此必须通过 31 |
day-of-week |
介于 由于此属性名称包含短划线,因此必须通过 7 |
hour |
介于 23 |
minute |
介于 59 |
month |
介于 12 |
second |
介于 59 |
timezone |
时区。 UTC |
triggerUid |
触发此事件的触发器的 ID。 4034124084959907503 |
week-of-year |
介于 由于此属性名称包含短划线,因此必须通过 52 |
year |
本年。 2015 |