簡易觸發條件

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

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

triggers/triggers.gs
/**
 * 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 表單的開啟事件,而是當編輯者開啟表單進行修改時,不會發生這類事件。