觸發條件可讓 Apps Script 在發生特定事件 (例如開啟文件) 時自動執行函式。簡易觸發條件是 Apps Script 內建的一組預留函式,例如 onOpen(e)
函式,會在使用者開啟 Google 文件、試算表、簡報或表單檔案時執行這類函式。可安裝觸發條件的功能比簡易觸發條件更多,但必須先啟用才能使用。針對這兩種觸發條件,Apps Script 都會傳遞觸發事件的事件物件,其中包含事件發生的情境相關資訊。
開始使用
如要使用簡單的觸發條件,只要建立使用其中一個預留函式名稱的函式即可:
onOpen(e)
會在使用者開啟試算表、文件、簡報或表單時,顯示使用者有權編輯的檔案。- 當使用者從 Google 文件、試算表、簡報或表單安裝編輯器外掛程式時,會執行
onInstall(e)
。 - 當使用者在試算表中變更值時,
onEdit(e)
就會執行。 - 當使用者在試算表中變更所選項目時,系統就會執行
onSelectionChange(e)
。 - 使用者造訪網頁應用程式或程式傳送 HTTP
GET
要求給網頁應用程式時,系統就會執行doGet(e)
。 - 當程式將 HTTP
POST
要求傳送至網頁應用程式時,就會執行doPost(e)
。
上述函式名稱中的 e
參數是傳遞至函式的事件物件。物件包含導致觸發觸發條件的結構定義相關資訊,但您可以視情況選用。
限制
由於簡易觸發條件會自動觸發,且無須要求使用者授權,因此會受到下列限制:
- 指令碼必須繫結至 Google 試算表、簡報、文件或表單檔案,或是做為擴充其中一個應用程式的外掛程式。
- 如果檔案以唯讀 (檢視或註解) 模式開啟,則無法執行。
- 指令碼執行作業和 API 要求並不會導致觸發條件執行。舉例來說,呼叫
Range.setValue()
來編輯儲存格,並不會導致試算表的onEdit
觸發條件執行。 - 他們無法存取需要授權的服務。舉例來說,Gmail 服務需要授權,但簡單的觸發條件可以透過語言服務以匿名方式翻譯詞組,因此簡易觸發條件無法傳送電子郵件。
- 他們可以修改要繫結的檔案,但因為需要授權而無法存取其他檔案。
- 視複雜的安全性限制而定,他們不一定能確定目前使用者的身分。
- 播放時間超過 30 秒。
- 在某些情況下,編輯器外掛程式會在無授權模式中執行
onOpen(e)
和onEdit(e)
簡易觸發條件,藉此顯示一些額外資料複雜性。詳情請參閱外掛程式授權生命週期指南。 - 簡易觸發條件必須遵守 Apps Script 觸發條件配額限制。
這些限制不適用於 doGet(e)
或 doPost(e)
。
onOpen(e)
當使用者開啟一份具備編輯權限的試算表、文件、簡報或表單時,onOpen(e)
觸發條件就會自動執行。(回覆表單時,只有在開啟表單進行編輯時,觸發條件才會執行。)onOpen(e)
最常用於在 Google 試算表、簡報、文件或表單中新增自訂選單項目。
onInstall(e)
當使用者從 Google 文件、試算表、簡報或表單安裝編輯器外掛程式時,onInstall(e)
觸發條件就會自動執行。使用者從 Google Workspace Marketplace 網站安裝這個外掛程式時,系統不會執行觸發條件。請注意,onInstall(e)
對於可執行的操作有特定限制,進一步瞭解授權。最常見的 onInstall(e)
只是呼叫 onOpen(e)
來新增自訂選單。安裝外掛程式後,系統就會開啟外掛程式,除非已重新開啟檔案,否則 onOpen(e)
不會自行執行。
onEdit(e)
當使用者變更試算表中任何儲存格的值時,onEdit(e)
觸發條件就會自動執行。大部分的 onEdit(e)
觸發條件都會使用事件物件中的資訊做出適當的回應。例如,以下 onEdit(e)
函式會在儲存格上設定註解,記錄上次編輯時間。
onSelectionChange(e)
當使用者在試算表中變更選項時,onSelectionChange(e)
觸發條件會自動執行。如要啟用此觸發條件,您必須在新增觸發條件後及每次開啟試算表時重新整理試算表。
如果選擇在短時間內於多個儲存格之間移動,系統可能會略過部分選取變更事件來縮短延遲時間。例如,如果選取動作彼此相隔兩秒,則只有第一次和最後一個選擇變更會啟動 onSelectionChange(e)
觸發條件。
在下例中,如果選取空白儲存格,onSelectionChange(e)
函式會將儲存格的背景設為紅色。
doGet(e)
和doPost(e)
doGet(e)
觸發條件會在使用者造訪網頁應用程式或程式將 HTTP GET
要求傳送至網頁應用程式時,自動執行該動作。當程式傳送 HTTP POST
要求給網頁應用程式時,doPost(e)
就會執行這些觸發條件。在網頁應用程式、HTML 服務和內容服務指南中,我們會提供更多觸發條件。請注意,doGet(e)
和 doPost(e)
不受上述限制。
可用的觸發條件類型
如果簡易觸發條件的限制無法滿足需求,系統可能會改用可安裝的觸發條件。下表匯總了各種事件類型可以使用的觸發條件類型。舉例來說,Google 試算表、簡報、表單和文件都支援簡單的開啟觸發條件,但只有 Google 試算表、文件和表單支援可安裝的開啟觸發條件。
事件 | 簡易觸發條件 | 可安裝的觸發條件 |
---|---|---|
開啟 |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
編輯 |
![]()
|
![]() |
選取項目變更 |
![]()
|
|
安裝 |
![]() ![]() ![]() ![]()
|
|
轉乘 |
![]() |
|
提交表單 |
![]() ![]() |
|
時間 (時鐘) |
![]() ![]() ![]() ![]() ![]() ![]() |
|
取得 |
![]() ![]()
|
|
貼文 |
![]() ![]()
|
* 使用者開啟表單來回應表單時,系統不會開啟 Google 表單的開啟事件,但會開啟表單進行修改。