事件物件

如果發生特定事件，Google Apps Script 可透過簡單觸發條件和可安裝的觸發條件自動執行函式。觸發條件觸發時，Apps Script 會將事件物件做為引數傳遞至函式，通常是 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());
}

本頁面說明不同類型觸發條件的事件物件欄位。

可安裝的觸發條件產生的事件包含 triggerUid，可識別產生事件的觸發條件。這有助於指令碼使用多個可安裝的觸發條件。

Google 試算表活動

透過各種 Google 試算表專屬觸發條件，指令碼可以回應使用者在試算表中的動作。

開啟 (簡單且可安裝)
`authMode`	`ScriptApp.AuthMode` 列舉的值。 LIMITED
`source`	`Spreadsheet` 物件，代表指令碼繫結的試算表檔案。 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` 物件，代表指令碼繫結的試算表檔案。 Spreadsheet
`triggerUid`	產生這個事件的觸發條件 ID。 4034124084959907503
`user`	`User` 物件，代表有效使用者 (如有) (視一組複雜的安全限制而定)。 amin@example.com

編輯 (簡單且可安裝)
`authMode`	`ScriptApp.AuthMode` 列舉的值。 LIMITED
`oldValue`	編輯前儲存格的值 (如有)。只有在編輯的範圍是單一儲存格時，才能使用這項功能。如果儲存格先前沒有內容，則為未定義。 1234
`range`	`Range` 物件，代表已編輯的儲存格或儲存格範圍。 Range
`source`	`Spreadsheet` 物件，代表指令碼繫結的試算表檔案。 Spreadsheet
`triggerUid`	產生此事件的觸發條件 ID (僅限可安裝的觸發條件)。 4034124084959907503
`user`	`User` 物件，代表有效使用者 (如有) (視一組複雜的安全限制而定)。 amin@example.com
`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', 'amin@example.com', 'Bob', '27', 'Bill', '28', 'Susan', '25']

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 表單活動

表單專屬的觸發條件可讓指令碼在使用者編輯表單或提交回覆時做出回應。

開啟 * (簡單且可安裝)
`authMode`	`ScriptApp.AuthMode` 列舉的值。 LIMITED
`source`	`Form` 物件，代表指令碼繫結的 Google 表單檔案。 Form
`triggerUid`	產生此事件的觸發條件 ID (僅限可安裝的觸發條件)。 4034124084959907503
`user`	`User` 物件，代表有效使用者 (如有) (視一組複雜的安全限制而定)。 amin@example.com

* 使用者開啟表單回覆時不會觸發這項事件，只有編輯者開啟表單進行修改時才會觸發。

提交表單 (可安裝)
注意：請務必搭配 `FormTriggerBuilder` 使用這個表單提交觸發條件。
`authMode`	`ScriptApp.AuthMode` 列舉的值。 FULL
`response`	`FormResponse` 物件，代表使用者對整個表單的回應。 FormResponse
`source`	`Form` 物件，代表指令碼繫結的 Google 表單檔案。 Form
`triggerUid`	產生這個事件的觸發條件 ID。 4034124084959907503

Google 日曆活動

當使用者更新日曆活動 (建立、編輯或刪除) 時，Google 日曆會觸發事件。

這些觸發條件不會說明變更的事件或變更方式。而是指出您的程式碼需要執行增量同步作業，才能擷取日曆的近期變更。如要完整瞭解這項程序，請參閱 Calendar API 的資源同步指南。

如要使用 Apps Script 與 Google 日曆同步，請按照下列步驟操作：

為指令碼專案啟用 Google 日曆進階服務。內建的「日曆」服務無法滿足這項工作流程的需求。
決定要同步處理哪些日曆。針對每個日曆，使用 Calendar 進階服務的 Events.list() 方法執行初始同步作業。
初始同步會傳回該日曆的 nextSyncToken。請儲存這個權杖，稍後會用到。
當 Apps Script EventUpdated 觸發條件觸發，指出日曆活動有變更時，請使用儲存的 nextSyncToken，對受影響的日曆執行增量同步。這基本上是另一個 Events.list() 請求，但提供 nextSyncToken 會將回應限制為僅包含上次同步後變更的事件。
檢查同步作業的回應，瞭解更新了哪些事件，並讓程式碼做出適當回應。例如記錄變更、更新試算表、傳送電子郵件通知，或執行其他動作。
使用增量同步要求傳回的 nextSyncToken，更新該日曆儲存的 nextSyncToken。這會強制下一次同步作業只傳回最新的變更。

伺服器有時會使同步權杖失效，導致發生 410 錯誤。此時，程式碼應執行「完整同步」，並取代該日曆的所有已儲存同步資料和權杖。

EventUpdated (可安裝)
`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