簡易觸發條件

觸發條件可讓 Apps Script 在發生特定事件 (例如開啟文件) 時自動執行函式。簡單觸發程序是 Apps Script 內建的一組預留函式，例如 onOpen(e) 函式，會在使用者開啟 Google 文件、試算表、簡報或表單檔案時執行。可安裝的觸發條件比簡單觸發條件的功能更多，但必須先啟用才能使用。無論是哪種觸發條件，Apps Script 都會將事件物件傳遞至觸發的函式，其中包含事件發生時的環境資訊。

注意： 如要瞭解如何在 Google Workspace 外掛程式專案中使用觸發條件，請參閱「Google Workspace 外掛程式的觸發條件」。

開始使用

如要使用簡單觸發程序，只要建立使用下列其中一個保留函式名稱的函式即可：

• 使用者開啟有權編輯的試算表、文件、簡報或表單時，系統會執行 onOpen(e)。
• onInstall(e)會在使用者從 Google 文件、試算表、簡報或表單中安裝編輯器外掛程式時執行。
• 當使用者變更試算表中的值時，系統會執行 onEdit(e)。
• 使用者變更試算表中的選取範圍時，系統會執行 onSelectionChange(e)。
• doGet(e) 會在使用者造訪網頁應用程式時執行， 或在程式將 HTTP GET 要求傳送至網頁應用程式時執行。
• 當程式將 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 試算表、簡報、文件或表單中新增自訂選單項目。

triggers/triggers.gs

前往 GitHub 查看

/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

使用者在 Google 文件、試算表、簡報或表單中安裝編輯器外掛程式時，onInstall(e)觸發程序會自動執行。使用者從 Google Workspace Marketplace 網站安裝外掛程式時，不會觸發這個事件。請注意，onInstall(e) 的功能會受到限制，如要進一步瞭解授權，請參閱這篇文章。onInstall(e) 最常見的用途是呼叫 onOpen(e) 來新增自訂選單。畢竟，安裝外掛程式時，檔案已開啟，因此除非重新開啟檔案，否則 onOpen(e) 不會自行執行。

triggers/triggers.gs

前往 GitHub 查看

/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

當使用者變更試算表中任何儲存格的值時，onEdit(e) 觸發程序會自動執行。大多數 onEdit(e) 觸發程序都會使用事件物件中的資訊，做出適當的回應。舉例來說，下列 onEdit(e) 函式會在儲存格中設定註解，記錄上次編輯時間。

triggers/triggers.gs

前往 GitHub 查看

/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

注意： onEdit() 觸發條件最多只會將 2 個觸發條件事件加入佇列。

onSelectionChange(e)

使用者變更試算表中的選取範圍時，onSelectionChange(e) 觸發程序會自動執行。如要啟用這項觸發條件，您必須在新增觸發條件後重新整理試算表，且每次開啟試算表時都必須重新整理。

如果選取範圍在短時間內於多個儲存格之間移動，系統可能會略過部分選取範圍變更事件，以減少延遲。舉例來說，如果使用者在兩秒內進行多次選取變更，只有第一次和最後一次選取變更會觸發 onSelectionChange(e) 觸發條件。

在下方範例中，如果選取空白儲存格，onSelectionChange(e) 函式會將儲存格的背景設為紅色。

triggers/triggers.gs

前往 GitHub 查看

/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e)和doPost(e)

當使用者造訪網頁應用程式，或程式將 HTTP GET 要求傳送至網頁應用程式時，doGet(e) 觸發程序會自動執行。當程式將 HTTP POST 要求傳送至網頁應用程式時，doPost(e) 會執行。如要進一步瞭解這些觸發程序，請參閱網頁應用程式、HTML 服務和 Content 服務指南。請注意，doGet(e) 和 doPost(e) 不受上述限制。

可用的觸發條件類型

如果簡單觸發條件的限制無法滿足您的需求，或許可以改用可安裝的觸發條件。下表摘要列出各類型事件可用的觸發條件類型。舉例來說，Google 試算表、簡報、表單和文件都支援簡單的開啟觸發條件，但只有試算表、文件和表單支援可安裝的開啟觸發條件。

活動	簡單觸發條件	可安裝的觸發條件
開啟	試算表 簡報 表單* 文件 function onOpen(e)	試算表 表單* 文件
編輯	試算表 function onEdit(e)	試算表
選取範圍變更	試算表 function onSelectionChange(e)
安裝	試算表 簡報 表單 文件 function onInstall(e)
變更		試算表
提交表單		試算表 表單
時間驅動 (時鐘)		試算表 簡報 表單 文件 獨立
取得	獨立 function doGet(e)
發布	獨立 function doPost(e)

* 如果使用者開啟 Google 表單是為了填寫回覆，系統不會觸發開啟事件，只有編輯者開啟表單進行修改時才會觸發。