事件物件

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

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

Google 試算表事件

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

開啟

(簡單易用且可安裝)
authMode

ScriptApp.AuthMode 列舉的值。

LIMITED
source

Spreadsheet 物件，代表指令碼繫結的 Google 試算表檔案。

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 物件，代表指令碼繫結的 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 表單活動

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 Script 與日曆同步，請執行下列步驟：

  1. 為指令碼專案啟用 日曆進階服務。內建的日曆服務無法滿足這個工作流程的需求。
  2. 決定要同步處理哪些日曆。針對每個日曆，使用日曆進階服務的 Events.list() 方法執行初始同步作業。
  3. 初次同步處理的結果會傳回該日曆的 nextSyncToken。請儲存這個憑證，以便日後使用。
  4. 當 Apps Script EventUpdated 觸發條件觸發，表示日曆事件有變更時，請使用儲存的 nextSyncToken 為受影響的日曆執行增量同步處理。這基本上是另一個 Events.list() 要求，但提供 nextSyncToken 會限制回應，只會顯示上次同步處理後變更的事件。
  5. 檢查同步處理的回應，瞭解有哪些事件已更新，且您的程式碼能適當回應。舉例來說，您可以記錄變更、更新試算表、傳送電子郵件通知，或採取其他行動。
  6. 使用漸進式同步要求傳回的 nextSyncToken，更新您為該日曆儲存的 nextSyncToken。這會強制下一次同步處理作業只傳回最新的變更。

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