簡易觸發條件

觸發條件可讓 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 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)

系統會在使用者安裝「onInstall(e)」觸發條件時，自動執行 內部編輯器外掛程式 Google 文件、試算表、簡報或表單。當使用者 在 Android 裝置上 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)

當使用者造訪以下網站時，系統會自動執行 doGet(e) 觸發條件 網頁應用程式或程式會傳送 HTTP GET 要求 為網頁應用程式doPost(e)當程式傳送 HTTP POST 要求至 網頁應用程式。這份指南進一步說明瞭 網頁應用程式、HTML 服務、 和 內容服務。請注意，doGet(e) 和 doPost(e) 不受上述限制約束。

可用的觸發條件類型

如果簡易觸發條件的限制 導致這些元素無法會議 您需要的可安裝觸發條件 。下表摘要說明觸發的觸發條件類型 分別指派不同的事件例如 Google 試算表、簡報、表單 Google 文件的所有功能都支援簡單的開啟觸發條件，但僅支援試算表、文件和表單 可安裝的開啟觸發條件

活動 簡易觸發條件 可安裝的觸發條件
開啟
試算表
簡報
表單*
文件

function onOpen(e)
試算表
表單*
文件
編輯
試算表

function onEdit(e)
試算表
選項變更
試算表

function onSelectionChange(e)
安裝
試算表
簡報
表單
文件

function onInstall(e)
變更
試算表
提交表單
試算表
表單
時間導向 (時鐘)
試算表
簡報
表單
文件
獨立式
取得
獨立式

function doGet(e)
訊息
獨立式

function doPost(e)

* 當使用者開啟 表單回覆，但建議編輯者開啟表單修改表單。