簡易觸發條件

觸發事件可讓 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 服務和內容服務的指南。請注意，doGet(e) 和 doPost(e) 不受上述限制。

可用的觸發條件類型

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

活動	簡單的觸發條件	可安裝的觸發條件
開啟	function onOpen(e)
編輯	function onEdit(e)
選取項目變更	function onSelectionChange(e)
安裝	function onInstall(e)
變更
提交表單
時間驅動 (時鐘)
取得	function doGet(e)
訊息	function doPost(e)

* 使用者開啟表單並回覆時，Google 表單不會觸發開啟事件，而是編輯者開啟表單並修改時才會觸發。