簡易觸發條件

觸發條件可讓 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 試算表、簡報、文件或表單中新增自訂選單項目。

trigger/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) 不會自行執行。

trigger/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) 函式會在儲存格上設定註解，記錄上次編輯時間。

trigger/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) 函式會將儲存格的背景設為紅色。

trigger/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)

doGet(e) 觸發條件會在使用者造訪網頁應用程式或程式將 HTTP GET 要求傳送至網頁應用程式時，自動執行該動作。當程式傳送 HTTP POST 要求給網頁應用程式時，doPost(e) 就會執行這些觸發條件。在網頁應用程式、HTML 服務和內容服務指南中，我們會提供更多觸發條件。請注意，doGet(e) 和 doPost(e) 不受上述限制。

可用的觸發條件類型

如果簡易觸發條件的限制無法滿足需求，系統可能會改用可安裝的觸發條件。下表匯總了各種事件類型可以使用的觸發條件類型。舉例來說，Google 試算表、簡報、表單和文件都支援簡單的開啟觸發條件，但只有 Google 試算表、文件和表單支援可安裝的開啟觸發條件。

事件	簡易觸發條件	可安裝的觸發條件
開啟	試算表 簡報 表單* 文件 function onOpen(e)	試算表 表單* 文件
編輯	試算表 function onEdit(e)	試算表
選取項目變更	試算表 function onSelectionChange(e)
安裝	試算表 簡報 表單 文件 function onInstall(e)
轉乘		試算表
提交表單		試算表 表單
時間 (時鐘)		試算表 簡報 表單 文件 協作平台 獨立
取得	協作平台 獨立 function doGet(e)
貼文	協作平台 獨立 function doPost(e)

* 使用者開啟表單來回應表單時，系統不會開啟 Google 表單的開啟事件，但會開啟表單進行修改。