事件对象

借助简单触发器和可安装的触发器，Apps 脚本可以在特定事件发生时自动运行函数。当触发器触发时，Apps 脚本会将事件对象作为实参传递给函数，该实参通常称为 e。事件对象包含有关导致触发器触发的上下文的信息。例如，以下示例代码展示了一个简单的 onEdit(e) 触发器，用于触发 Google 表格脚本，该脚本使用事件对象来确定编辑了哪个单元格。

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());
}

本页详细介绍了不同类型的触发器的事件对象中的字段。

由可安装的触发器生成的事件包含一个 triggerUid，用于标识生成该事件的触发器。 这对于具有多个可安装触发器的脚本很有用。

Google 表格活动

各种 Google 表格专用触发器可让脚本响应用户在电子表格中的操作。

打开 （简单且可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 LIMITED
source	一个 Spreadsheet 对象，表示脚本所绑定的 Google 表格文件。 Spreadsheet
triggerUid	生成相应事件的触发器的 ID（仅限可安装的触发器）。 4034124084959907503
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]

更改 （可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 FULL
changeType	更改类型（EDIT、INSERT_ROW、INSERT_COLUMN、REMOVE_ROW、REMOVE_COLUMN、INSERT_GRID、REMOVE_GRID、FORMAT 或 OTHER）。 INSERT_ROW
source	一个 Spreadsheet 对象，表示脚本所绑定的 Google 表格文件。 Spreadsheet
triggerUid	生成相应事件的触发器的 ID。 4034124084959907503
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]

修改 （简单且可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 LIMITED
oldValue	编辑之前的单元格值（如果有）。仅在修改的范围为单个单元格时可用。如果相应单元格之前没有内容，则为未定义。 1234
range	一个 Range 对象，表示已修改的单元格或单元格范围。 Range
source	一个 Spreadsheet 对象，表示脚本所绑定的 Google 表格文件。 Spreadsheet
triggerUid	生成相应事件的触发器的 ID（仅限可安装的触发器）。 4034124084959907503
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]
value	修改后的新单元格值。仅在修改的范围为单个单元格时可用。 10

表单提交 （可安装）
注意：请务必将此表单提交触发器与 SpreadsheetTriggerBuilder 一起使用。
authMode	ScriptApp.AuthMode 枚举中的值。 FULL
namedValues	一个对象，包含表单提交中的问题名称和值。 { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] }
range	一个 Range 对象，表示已修改的单元格或单元格范围。 Range
triggerUid	生成相应事件的触发器的 ID。 4034124084959907503
values	数组，其中的值与它们在电子表格中的显示顺序相同。 ['2015/05/04 15:00', '[e-mail]', 'Bob', '27', 'Bill', '28', 'Susan', '25']

Google 文档活动

触发器可让 Google 文档在用户打开文档时做出响应。

打开 （简单且可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 LIMITED
source	一个 Document 对象，表示脚本所绑定的 Google 文档文件。 Document
triggerUid	生成相应事件的触发器的 ID（仅限可安装的触发器）。 4034124084959907503
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]

Google 幻灯片活动

触发器可让 Google 幻灯片在用户打开演示文稿时做出响应。

打开 （简单）
authMode	ScriptApp.AuthMode 枚举中的值。 LIMITED
source	一个 Presentation 对象，表示脚本所绑定的 Google 幻灯片文件。 Presentation
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]

Google 表单活动

借助 Google 表单专用触发器，脚本可以在用户修改表单或提交回复时做出响应。

打开 *（简单且可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 LIMITED
source	一个 Form 对象，表示脚本所绑定的 Google 表单文件。 Form
triggerUid	生成相应事件的触发器的 ID（仅限可安装的触发器）。 4034124084959907503
user	一个 User 对象，表示活跃用户（如果有）（取决于一组复杂的安全限制）。 [e-mail]

* 此事件不会在用户打开表单进行回复时发生，而是在编辑者打开表单进行修改时发生。

表单提交 （可安装）
注意：请务必将此表单提交触发器与 FormTriggerBuilder 一起使用。
authMode	ScriptApp.AuthMode 枚举中的值。 FULL
response	一个 FormResponse 对象，表示用户对整个表单的回答。 FormResponse
source	一个 Form 对象，表示脚本所绑定的 Google 表单文件。 Form
triggerUid	生成相应事件的触发器的 ID。 4034124084959907503

Google 日历活动

当用户的日历活动更新（创建、修改或删除）时，日历触发器会触发。

这些触发器不会告知您哪个事件发生了更改或更改方式。相反，它们表示您的代码需要执行增量同步操作才能获取日历的最新更改。如需详细了解此过程，请参阅 Calendar API 的同步资源指南。

如需在 Apps 脚本中与日历同步，请执行以下步骤：

1. 为脚本项目启用 Calendar 高级服务。内置的日历服务无法满足此工作流的需求。
2. 确定应同步哪些日历。对于每个此类日历，请使用日历高级服务的 Events.list() 方法执行初始同步操作。
3. 初始同步的结果会针对相应日历返回 nextSyncToken。存储此令牌以备后用。
4. 当 Apps 脚本 EventUpdated 触发器触发并指示日历活动发生更改时，使用存储的 nextSyncToken 对受影响的日历执行增量同步。这实际上是另一个 Events.list() 请求，但提供 nextSyncToken 会将响应限制为仅包含自上次同步以来发生变化的事件。
5. 检查同步的响应，了解哪些事件已更新，并让您的代码做出适当的响应。例如，您可以记录更改、更新电子表格、发送电子邮件通知或执行其他操作。
6. 使用增量同步请求返回的 nextSyncToken 更新您为相应日历存储的 nextSyncToken。这会强制下一次同步操作仅返回最新更改。

注意： 同步令牌有时会被服务器设为无效，从而导致 410 错误。发生这种情况时，您的代码应执行完全同步，并替换您为相应日历存储的所有已同步数据和令牌。

EventUpdated （可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 FULL
calendarId	发生活动更新的日历的字符串 ID。 [e-mail]
triggerUid	生成相应事件的触发器的 ID。 4034124084959907503

Google Workspace 加购项活动

当用户安装插件时，onInstall() 触发器会自动运行。

安装 （简单）
authMode	ScriptApp.AuthMode 枚举中的值。 FULL

Google Chat 应用事件

如需了解 Google Chat 中的事件对象，请参阅接收并响应与 Google Chat 应用的互动。

时间驱动的事件

借助基于时间的触发器（也称为时钟触发器），脚本可以在特定时间或按重复间隔执行。

时间驱动型（可安装）
authMode	ScriptApp.AuthMode 枚举中的值。 FULL
day-of-month	介于 1 和 31 之间。 由于此属性名称包含短划线，因此必须通过 e['day-of-month'] 而不是点表示法来访问。 31
day-of-week	介于 1（星期一）和 7（星期日）之间。 由于此属性名称包含短划线，因此必须通过 e['day-of-week'] 而不是点表示法来访问。 7
hour	介于 0 和 23 之间。 23
minute	介于 0 和 59 之间。 59
month	介于 1 和 12 之间。 12
second	介于 0 和 59 之间。 59
timezone	时区。 UTC
triggerUid	生成相应事件的触发器的 ID。 4034124084959907503
week-of-year	介于 1 和 52 之间。 由于此属性名称包含短划线，因此必须通过 e['week-of-year'] 而不是点表示法来访问。 52
year	本年。 2015