事件对象

简单触发器和可安装的触发器可让 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

来自 ScriptApp.AuthMode 枚举的值。

LIMITED
source

Spreadsheet 对象，表示脚本绑定到的 Google 表格文件。

Spreadsheet
triggerUid

生成此事件的触发器的 ID（仅限可安装的触发器）。

4034124084959907503
user

User 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com

换乘

（可安装）
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 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com

修改

（简单且可安装）
authMode

来自 ScriptApp.AuthMode 枚举的值。

LIMITED
oldValue

修改之前的单元格值（如果有）。仅当已修改的范围为单个单元格时可用。如果单元格之前没有内容，则未定义。

1234
range

Range 对象，表示已修改的单元格或单元格范围。

Range
source

Spreadsheet 对象，表示脚本绑定到的 Google 表格文件。

Spreadsheet
triggerUid

生成此事件的触发器的 ID（仅限可安装的触发器）。

4034124084959907503
user

User 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com
value

修改后的新单元格值。仅当已修改范围为单个单元格时可用。

10

提交表单

（可安装）
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', 'amin@example.com', 'Bob', '27', 'Bill',
'28', 'Susan', '25']

Google 文档活动

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

打开

（简单且可安装）
authMode

来自 ScriptApp.AuthMode 枚举的值。

LIMITED
source

Document 对象，表示脚本绑定到的 Google 文档文件。

Document
triggerUid

生成此事件的触发器的 ID（仅限可安装的触发器）。

4034124084959907503
user

User 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com

Google 幻灯片活动

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

打开

（简单）
authMode

来自 ScriptApp.AuthMode 枚举的值。

LIMITED
source

Presentation 对象，表示脚本绑定到的 Google 幻灯片文件。

Presentation
user

User 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com

Google 表单活动

Google 表单专用触发器允许脚本在用户修改表单或提交响应时进行响应。

打开

* （简单且可安装）
authMode

来自 ScriptApp.AuthMode 枚举的值。

LIMITED
source

Form 对象，表示脚本绑定到的 Google 表单文件。

Form
triggerUid

生成此事件的触发器的 ID（仅限可安装的触发器）。

4034124084959907503
user

User 对象，表示活跃用户（如果有），具体取决于一组复杂的安全限制。

amin@example.com

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

提交表单

（可安装）
authMode

来自 ScriptApp.AuthMode 枚举的值。

FULL
response

FormResponse 对象，表示用户对表单的整体响应。

FormResponse
source

Form 对象，表示脚本绑定到的 Google 表单文件。

Form
triggerUid

生成此事件的触发器的 ID。

4034124084959907503

Google 日历活动

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

这些触发器不会告知您哪个事件发生了变化或其更改方式。而是表示您的代码需要执行增量同步操作才能获取日历的最近更改。有关此过程的完整说明，请参阅 Calendar API 的同步资源指南。

如要通过 Apps 脚本与 Google 日历同步，请执行以下步骤：

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

活动已更新

（可安装）
authMode

来自 ScriptApp.AuthMode 枚举的值。

FULL
calendarId

发生了活动更新的日历的字符串 ID。

susan@example.com
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