編輯器外掛程式觸發事件

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

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

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

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

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

您可以在編輯器外掛程式中使用 Google Apps Script 專案提供的大部分一般觸發條件類型，包括簡單觸發條件和大部分可安裝的觸發條件。可用的觸發條件類型組合取決於要擴充的應用程式。

與編輯器外掛程式不同，Google Workspace 外掛程式無法使用一般 Apps Script 簡易或可安裝的觸發條件。而是使用專為 Google Workspace 外掛程式設計的觸發條件。詳情請參閱「Google Workspace 外掛程式觸發條件」。

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

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

* 如果使用者開啟表單是為了回覆，系統不會觸發 Google 表單的開啟事件，但如果編輯者開啟表單是為了修改，系統就會觸發。

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

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

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

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

限制

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

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

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

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

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

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

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

• 表單提交可安裝的觸發條件會在提交 Google 表單回覆時執行。

  表單提交觸發條件有兩個版本：一個適用於 Google 試算表 (收集表單回覆)，另一個適用於 Google 表單。傳遞至 Google 試算表表單提交觸發函式的事件物件較為簡單，且會以簡單陣列形式傳回回應值。傳遞至 Google 表單表單提交觸發函式的事件物件會提供更多資訊，這些資訊包含在 FormResponse 物件中。

• 時間觸發條件 (也稱為時鐘觸發條件) 會在特定時間觸發，或以規律的時間間隔重複觸發。

授權可安裝的觸發條件

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

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

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

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

/**
 * 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.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

限制

外掛程式中的可安裝觸發條件，與其他類型的 Apps Script 專案一樣，都受到相同的限制。

除了上述限制外，外掛程式中可安裝的觸發條件還受到下列限制：

• 每位使用者在每個文件中，每種外掛程式只能有一個觸發條件。舉例來說，在特定試算表中，特定使用者只能有一個編輯觸發條件，但使用者也可以在同一份試算表中設定表單提交觸發條件或時間觸發條件。如果其他使用者也能存取同一份試算表，他們可以擁有自己的一組觸發條件。
• 外掛程式只能為使用該外掛程式的檔案建立觸發條件。也就是說，在 Google 文件 A 中使用的外掛程式無法建立觸發條件，監控 Google 文件 B 何時開啟。
• 時間觸發條件的執行頻率不得超過每小時一次。
• 如果可安裝的觸發程序執行的程式碼擲回例外狀況，外掛程式不會自動傳送電子郵件給使用者。開發人員有責任檢查並妥善處理失敗案例。
• 在下列任一情況下，外掛程式觸發條件會停止觸發：
  • 如果使用者解除安裝外掛程式，
  • 如果外掛程式在文件中停用 (重新啟用後，觸發程序會再次運作)，或
  • 如果開發人員取消發布外掛程式，或將損壞的版本提交至外掛程式商店。
• 外掛程式觸發函式會執行，直到程式碼使用未經授權的服務為止，此時函式就會停止執行。只有在發布外掛程式時，這項說法才成立；如果指令碼的任何部分需要授權，則在一般 Apps Script 專案或未發布的外掛程式中，相同的觸發程序完全不會執行。
• 可安裝的觸發條件會受到 Apps Script 觸發條件配額限制。