事件物件

如果發生特定事件，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 與 Google 日曆同步，請按照下列步驟操作：

1. 為指令碼專案啟用 Calendar 進階服務。內建的日曆服務無法滿足這個工作流程的需求。
2. 決定要同步處理哪些日曆。針對每個這類日曆，使用 Calendar 進階服務的 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