本頁面由 Cloud Translation API 翻譯而成。

編輯器外掛程式觸發事件

Apps Script 觸發條件會在指定事件發生時，執行指定的指令碼函式 (即觸發函式)。只有特定事件會觸發動作，且每個 Google Workspace 應用程式支援的事件都不盡相同。

觸發條件啟動時，系統會建立事件物件。這個 JSON 結構包含發生的事件詳細資料。事件物件結構中的資訊會根據觸發類型，以不同方式整理。

建立事件物件後，Apps Script 會將其做為參數傳遞至觸發函式。觸發函式是您必須自行實作的回呼函式，可採取適當的動作來回應事件。舉例來說，在編輯器外掛程式中，開啟文件時會使用觸發條件建立外掛程式選單項目。在本例中，您會實作 onOpen(e) 觸發函式，建立外掛程式所需的選單項目，可能需要使用事件物件中的資料。

本頁提供在編輯器外掛程式專案中使用觸發條件的準則。

編輯器外掛程式觸發條件類型

您可以在編輯器外掛程式中使用 Apps Script 專案提供的大部分一般觸發條件類型，包括簡易觸發條件和大多數可安裝的觸發條件。可用的觸發條件類型組合會因擴充的應用程式而異。

下表列出 Editor 外掛程式可使用的簡單和可安裝的觸發條件類型，並提供對應事件物件的連結：

活動	事件物件	簡單觸發條件	可安裝的觸發條件
開啟系統會開啟編輯器檔案。	文件 onOpen 事件物件表單 onOpen 事件物件試算表 onOpen 事件物件簡報 onOpen 事件物件	文件表單* 試算表簡報 `function onOpen(e)`	文件表單試算表
安裝外掛程式已安裝。	onInstall 事件物件	文件表單試算表簡報 `function onInstall(e)`
編輯試算表儲存格內容已變更。	Sheets onEdit event object	試算表 `function onEdit(e)`	試算表
變更編輯或設定試算表內容的格式。	Sheets onChange event object		試算表
Form-submit ：提交 Google 表單。	表單表單提交事件物件試算表表單提交事件物件		表單試算表
時間驅動 (時鐘) 觸發條件會在指定時間或間隔觸發。	時間驅動事件物件		文件表單試算表簡報

* 如果使用者開啟 Google 表單是為了填寫回覆，系統不會觸發開啟事件，只有編輯者開啟表單進行修改時才會觸發。

外掛程式中的簡易觸發條件

簡單觸發程序會使用一組保留的函式名稱，無法使用需要授權的服務，且會自動啟用以供使用。在某些情況下，簡單觸發事件可改由可安裝的觸發條件處理。

如要為外掛程式新增簡單觸發條件，只要實作函式，並使用下列其中一個保留名稱即可：

使用者開啟文件、試算表或簡報時，系統會執行 onOpen(e)。在編輯器中開啟表單時 (但不是在回覆表單時)，onOpen(e) 也可以執行。只有在使用者有權編輯相關檔案時，這項函式才會執行，且最常用於建立選單項目。
使用者安裝外掛程式時，系統會執行 onInstall(e)。通常 onInstall(e) 只是用來呼叫 onOpen(e)，確保外掛程式選單會在安裝後立即顯示，使用者不必重新整理頁面。
使用者變更試算表中的儲存格值時，系統會執行 onEdit(e)。如果儲存格移動、格式設定或其他變更不會改變儲存格值，就不會觸發這個觸發條件。

限制

外掛程式中的簡易觸發條件與其他類型的 Apps Script 專案一樣，都受到相同的限制。設計外掛程式時，請特別留意下列限制：

如果檔案是以唯讀 (檢視或留言) 模式開啟，簡單觸發程序就不會執行。這項行為會導致外掛程式選單無法填入資料。
在某些情況下，編輯器外掛程式會在無授權模式下執行 onOpen(e) 和 onEdit(e) 簡單觸發條件。如外掛程式授權模式所述，這個模式會帶來一些額外的複雜情況。
簡單觸發程序無法使用服務，或執行其他需要授權的動作，但外掛程式授權模型中列出的動作除外。
簡單觸發程序無法執行超過 30 秒。請盡量減少在簡單觸發函式中執行的處理作業量。
簡單觸發程序會受到 Apps Script 觸發程序配額限制。

外掛程式中可安裝的觸發條件

外掛程式可使用 Apps Script Script 服務，以程式輔助方式建立及修改可安裝的觸發條件。外掛程式可安裝的觸發條件無法手動建立。與簡單觸發程序不同，可安裝的觸發程序可以使用需要授權的服務。

外掛程式中的可安裝觸發條件發生錯誤時，不會傳送錯誤電子郵件給使用者，因為使用者通常無法解決問題。因此，請盡可能設計外掛程式，代表使用者妥善處理錯誤。

外掛程式可使用下列可安裝的觸發條件：

使用者開啟文件、試算表，或在編輯器中開啟表單時 (但回覆表單時不會)，系統會執行「開啟」可安裝的觸發條件。
使用者變更試算表中的儲存格值時，系統會執行編輯可安裝的觸發條件。如果格式或其他變更不會改變儲存格值，就不會觸發這項觸發條件。
變更可安裝的觸發條件會在使用者對試算表進行任何變更時執行，包括格式編輯和修改試算表本身 (例如新增列)。
表單提交可安裝的觸發條件會在提交 Google 表單回覆時執行。

注意： 表單提交觸發程序有兩個版本，一個適用於 Google 試算表 (收集表單回覆)，另一個適用於 Google 表單。傳遞至試算表表單提交觸發函式的事件物件較為簡單，且會以簡單陣列形式傳回回應值。傳遞至表單提交觸發函式的事件物件，會提供更多資訊，這些資訊包含在 FormResponse 物件中。
時間觸發條件 (也稱為時鐘觸發條件) 會在特定時間觸發，或以規律的時間間隔重複觸發。

授權可安裝的觸發條件

一般來說，如果開發人員更新外掛程式，改用需要額外授權的新服務，使用者下次使用外掛程式時，系統會提示他們重新授權。

不過，使用觸發條件的外掛程式會遇到特殊的授權問題。假設有個外掛程式會使用觸發條件監控表單提交情形：表單建立者第一次使用外掛程式時可能會授權，然後讓外掛程式執行數月或數年，期間從未重新開啟表單。如果外掛程式開發人員更新外掛程式，使用需要額外授權的新服務，表單建立者永遠不會看到重新授權對話方塊，因為他們從未重新開啟表單，外掛程式也會停止運作。

與一般 Apps Script 專案中的觸發條件不同，外掛程式中的觸發條件即使需要重新授權，仍會繼續觸發。不過，如果指令碼遇到需要授權的程式碼行，但指令碼沒有授權，指令碼仍會失敗。為避免這種情況，開發人員可以使用 ScriptApp.getAuthorizationInfo() 方法，控管外掛程式發布版本之間變更部分的程式碼存取權。

以下範例說明觸發函式中建議使用的結構，可避免授權陷阱。範例觸發函式會回應 Google 試算表外掛程式中的表單提交事件，並在需要重新授權時，使用範本 HTML 傳送警示電子郵件給外掛程式使用者。

Code.gs

triggers/form/Code.gs

前往 GitHub 查看

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html