編輯器外掛程式觸發事件

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

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

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

本頁面提供編輯器外掛專案中使用觸發條件的規範。

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

您可以在編輯器外掛程式中使用大部分的通用觸發條件類型，包括簡易觸發條件和大部分的可安裝觸發條件。具體可用的觸發事件類型取決於要擴充的應用程式。

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

活動	事件物件	簡單觸發條件	可安裝的觸發條件
開啟 系統會開啟編輯器檔案。	Google 文件 onOpen 事件物件 表單 onOpen 事件物件 試算表 onOpen 事件物件 簡報 onOpen 事件物件	文件 表單* 試算表 簡報 function onOpen(e)	文件 表單 試算表
安裝 外掛程式已安裝。	onInstall 事件物件	文件 表單 試算表 簡報 function onInstall(e)
編輯 試算表儲存格內容已變更。	Sheets onEdit 事件物件	試算表 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 表單回覆時，系統會執行表單提交可安裝的觸發條件。

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

授權可安裝的觸發條件

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

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

與一般 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 觸發事件配額限制。