事件对象

借助简单触发器可安装的触发器,如果发生特定事件,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

更改类型(EDITINSERT_ROWINSERT_COLUMNREMOVE_ROWREMOVE_COLUMNINSERT_GRIDREMOVE_GRIDFORMATOTHER)。

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 Forms 事件

借助 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 脚本中的日历同步,请执行以下步骤:

  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

插件事件

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

安装

简单
authMode

来自 ScriptApp.AuthMode 枚举的值。

FULL

时间驱动的事件

时间驱动型触发器(也称为时钟触发器)可让脚本在特定时间或按周期性间隔执行。

时间驱动型(可安装)
authMode

来自 ScriptApp.AuthMode 枚举的值。

FULL
day-of-month

介于 131 之间。

由于此属性名称包含短划线,因此必须通过 e['day-of-month'](而非点表示法)对其进行访问。

31
day-of-week

介于 1(星期一)到 7(星期日)之间。

由于此属性名称包含短划线,因此必须通过 e['day-of-week'](而非点表示法)对其进行访问。

7
hour

介于 023 之间。

23
minute

介于 059 之间。

59
month

介于 112 之间。

12
second

介于 059 之间。

59
timezone

时区。

UTC
triggerUid

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

4034124084959907503
week-of-year

介于 152 之间。

由于此属性名称包含短划线,因此必须通过 e['week-of-year'](而非点表示法)对其进行访问。

52
year

本年。

2015