編輯器外掛程式的觸發條件

Apps Script 觸發條件會在發生指定事件時，觸發指定的指令碼函式 (觸發函式)。只有特定事件可能會導致觸發條件觸發，而且每個 Google Workspace 應用程式支援不同的事件組合。

觸發條件啟動時，系統會建立事件物件。此 JSON 結構包含發生事件的詳細資料。事件物件結構中的資訊因觸發條件類型而異。

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

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

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

您可以在編輯器外掛程式中，使用 Apps Script 專案適用的大多數一般觸發條件類型，包括簡易觸發條件和大部分可安裝的觸發條件。可用觸發條件類型確切取決於要擴充的應用程式。

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

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

事件	事件物件	簡易觸發條件	可安裝的觸發條件
開啟 開啟編輯器檔案。	開啟「Google 簡報」事件物件 表單 onOpen 活動物件 開啟的 Google 試算表物件 開啟活動物件的 Google 簡報	文件 表單* 試算表 簡報 function onOpen(e)	文件 表單 試算表
安裝 已安裝外掛程式。	onInstall 事件物件	文件 表單 試算表 簡報 function onInstall(e)
編輯 試算表儲存格內容已變更。	用於編輯事件物件的試算表	試算表 function onEdit(e)	試算表
變更 有人編輯工作表中的內容或設定格式。	試算表 onChange 事件物件		試算表
提交表單 提交 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 將快訊電子郵件的使用者傳送給外掛程式。

程式碼.gs

觸發條件/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.
  }
}

validationemail.html

觸發事件/form/AuthorizationEmail.html

前往 GitHub 查看

<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 觸發條件的配額限制。