簡易觸發條件

觸發條件可讓 Apps Script 在發生特定事件 (例如開啟文件) 時自動執行函式。簡易觸發條件是一組 Apps Script 內建的保留函式 (例如 onOpen(e) 函式)，會在使用者開啟 Google 文件、試算表、簡報或表單檔案時執行。「可安裝觸發條件」提供的功能比簡單的觸發條件更多，但必須在使用前啟用。對於這兩種觸發條件，Apps Script 會將觸發的函式傳送至事件物件，其中包含事件發生情境的資訊。

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

開始使用

如要使用簡易觸發條件，只要建立一個使用其中一個保留函式名稱的函式即可：

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

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 表單的開啟事件就不會發生。