事件物件

簡易觸發條件和可安裝的觸發條件可讓 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