簡易觸發條件

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

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

開始使用

如要使用簡單的觸發事件，只要建立使用下列保留函式名稱之一的函式即可：

• 當使用者開啟試算表、文件、簡報或表單，且具有編輯權限時，onOpen(e) 就會執行。
• 當使用者在 Google 文件、試算表、簡報或表單中安裝編輯器外掛程式時，onInstall(e) 就會執行。
• 當使用者變更試算表中的值時，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 服務和內容服務的指南。請注意，doGet(e) 和 doPost(e) 不受上述限制。

可用的觸發條件類型

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

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

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