編輯器外掛程式觸發條件

Apps Script 觸發條件造成指定的指令碼 函式 (觸發條件函式)，每當有指定事件時就會執行 會發生什麼事只有特定事件才會觸發觸發條件；而且 Google Workspace 應用程式支援不同的事件組合。

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

事件物件建立完成後，Apps Script 會將該物件以參數形式傳遞至 觸發函式。觸發函式是一種回呼函式，您必須 以便採取任何適當行動來回應 活動。例如，在編輯器外掛程式的觸發條件中 可用於在文件開啟時建立外掛程式選單項目。在這個範例中 對 onOpen(e) 觸發條件函式執行實作，以便透過外掛程式建立選單項目 可能需使用事件物件中的資料

本頁面提供在 編輯者 外掛程式專案

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

您可以使用 Apps Script 專案可用的大多數一般觸發條件類型 (包括簡易觸發條件) 和最可安裝的觸發條件 確切的可用觸發條件類型取決於擴充的應用程式。

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

活動 事件物件 簡易觸發條件 可安裝觸發條件
開啟
編輯器檔案已開啟。		 Google 文件 onOpen 事件物件
Forms onOpen 事件物件
Google 試算表開啟事件物件
Slides onOpen 事件物件 		文件
表單*
試算表
簡報

function onOpen(e)

 文件
表單
Google 試算表
安裝
已安裝外掛程式。		 onInstall 事件物件 文件
表單
試算表
簡報

function onInstall(e)
編輯
試算表儲存格內容已變更。		 Google 試算表編輯事件物件 試算表

function onEdit(e)

 試算表
變更
工作表內容經過編輯或設定格式。		 試算表 onChange 事件物件 試算表
提交表單
已提交 Google 表單。		 表單提交事件物件
試算表表單提交事件物件 		表單
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 試算表的 盡可能代表使用者妥善處理錯誤。

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

  • Open 的可安裝觸發條件會在使用者開啟文件時執行。 或在編輯器中開啟表單時 (但在回覆時無 這份表格)。
  • 當使用者變更儲存格中的儲存格值時，系統會執行編輯可安裝觸發條件 試算表。這項觸發條件不會因格式或其他問題而觸發 並不會變更儲存格的值
  • 變更可安裝的觸發條件會在使用者變更 試算表，包括對試算表所做的格式編輯和修改 (例如新增列)。

  • 表單提交可安裝觸發條件會在 Google 表單回覆出現時執行 就會引發這個事件。

  • 時間型觸發條件 (也稱為時鐘觸發條件) 會在特定時間啟動，或是在 固定的時間間隔

授權可安裝的觸發條件

通常，如果開發人員更新外掛程式，改為使用需要 額外的授權時，系統會提示使用者 使用時間。

然而，使用觸發條件的外掛程式會發生特殊授權挑戰。 假設有某個外掛程式使用觸發條件監控表單提交情形：表單 創作者首次使用外掛程式時，可能會授權給對方 執行數月或數年，也無需重新開啟表單。 如果外掛程式開發人員需要更新外掛程式，才能使用 需要額外的授權，表單建立者將看不到 重新授權對話方塊，因為這類使用者從未重新開啟表單和外掛程式 停止運作。

與一般 Apps Script 專案中的觸發條件不同， 這些附加服務會繼續啟動，即使需要重新授權也一樣。不過，指令碼 仍然失敗 (如出現需要授權指令碼的那行程式碼) 但實際上為避免發生這種情況，開發人員可以 ScriptApp.getAuthorizationInfo()敬上 針對在已發布版本之間變更的程式碼部分，限制其存取權

以下舉例說明在觸發條件函式中， 避免授權問題觸發條件函式範例會回應 Google 試算表外掛程式中的表單提交活動 (如果重新授權的話) 必要，使用範本 HTML 向外掛程式的使用者傳送快訊電子郵件。

Code.gs

triggers/form/Code.gs
/**
 * 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
<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 觸發條件影響 配額限制。