簡易觸發條件

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

開始使用

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

• 使用者開啟有權編輯的試算表、文件、簡報或表單時，系統會執行 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 試算表、簡報、文件或表單中新增自訂選單項目。

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

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

/**
 * 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());
}

onSelectionChange(e)

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

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

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

/**
 * 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 表單是為了填寫回覆，系統不會觸發開啟事件，只有編輯者開啟表單進行修改時才會觸發。