事件物件

簡易觸發條件和可安裝的觸發條件可讓 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 物件，代表指令碼繫結的 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 Script 與日曆同步，請執行下列步驟：

1. 為指令碼專案啟用 日曆進階服務。內建的日曆服務無法滿足這個工作流程的需求。
2. 決定要同步處理哪些日曆。針對每個日曆，使用日曆進階服務的 Events.list() 方法執行初始同步作業。
3. 初次同步處理的結果會傳回該日曆的 nextSyncToken。請儲存這個憑證，以便日後使用。
4. 當 Apps Script 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