Google Workspace 外掛程式的觸發條件
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
Apps Script 觸發條件會在指定事件發生時，執行指定的指令碼函式 (即觸發函式)。只有特定事件會觸發動作，且每個 Google Workspace 應用程式支援的事件都不盡相同。
觸發條件啟動時，系統會建立事件物件。這個 JSON 結構包含發生的事件詳細資料。事件物件結構中的資訊會根據觸發類型，以不同方式整理。
建立事件物件後，Apps Script 會將其做為參數傳遞至觸發函式。觸發函式是您必須自行實作的回呼函式，可採取適當的動作來回應事件。舉例來說，在擴充 Gmail 的 Google Workspace 外掛程式中，您可以定義觸發條件，在使用者開啟郵件串時建立新的資訊卡介面。在本例中，您會實作情境式回呼函式，使用事件物件中傳遞的資料建立構成新 UI 的資訊卡。
本頁面提供在 Google Workspace 外掛程式專案中使用觸發條件的相關指南。
資訊清單觸發條件
與編輯器外掛程式不同，Google Workspace 外掛程式目前無法使用 Apps Script 簡易觸發條件，而是使用專為 Google Workspace 外掛程式設計的觸發條件：資訊清單觸發條件。
資訊清單觸發條件完全是在 Google Workspace 外掛程式的資訊清單中定義。以下列舉一些觸發資訊清單的例子：
- 首頁觸發條件：建構及顯示外掛程式首頁。
- 日曆活動開啟觸發條件：在日曆活動開啟時顯示新資訊卡或採取其他動作。
- 日曆活動更新觸發條件：使用者編輯並儲存日曆活動時，顯示新資訊卡或採取其他動作。
- Drive onItemsSelected 觸發條件：使用者在雲端硬碟中選取一或多個檔案或資料夾時，系統會顯示新資訊卡或採取其他動作。
- Gmail 撰寫觸發條件：使用者在 Gmail 撰寫視窗中開啟外掛程式時，會顯示外掛程式資訊卡。
- Gmail 內容比對觸發條件：使用者開啟 Gmail 郵件時，顯示新資訊卡或採取其他動作。
- Editor onFileScopeGranted 觸發程序：當使用者在目前的 Google 試算表文件中授予
drive.file OAuth 範圍的授權時，系統會顯示新資訊卡。
在上述清單中，只有首頁觸發條件屬於非情境式觸發條件，其餘都是情境式觸發條件。如要進一步瞭解資訊清單觸發條件定義，請參閱資訊清單。
除了資訊清單觸發條件，Google Workspace 外掛程式也可以使用 Apps Script 可安裝的觸發條件。
限制
資訊清單觸發條件的使用方式有特定限制。
- 這些觸發條件僅適用於 Google Workspace 外掛程式專案，無法用於其他應用程式。
- 由於這些觸發條件是在外掛程式資訊清單中定義，而非程式碼中，因此您無法使用 Apps Script
Script 服務建立或修改這些觸發條件。
- Gmail 內容觸發條件目前只能有
unconditional 條件。也就是說，無論電子郵件內容為何，都會觸發內容比對觸發條件。
- 每位使用者在每個文件中，每種外掛程式只能有一個觸發條件。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-31 (世界標準時間)。
[null,null,["上次更新時間：2025-07-31 (世界標準時間)。"],[[["\u003cp\u003eApps Script triggers execute a specific function when a defined event occurs within a Google Workspace application.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Workspace add-ons utilize manifest triggers, defined in the add-on's manifest, to respond to events like opening a document or composing an email.\u003c/p\u003e\n"],["\u003cp\u003eManifest triggers can be contextual, reacting to specific user actions within a document or application, or non-contextual, like those that build the add-on's homepage.\u003c/p\u003e\n"],["\u003cp\u003eWhile manifest triggers offer event-driven functionality, they have limitations, including restrictions on their use and creation methods.\u003c/p\u003e\n"]]],["Apps Script triggers initiate a script function when specific events occur, creating an event object with event details. This object is then passed to a user-implemented trigger function, enabling actions based on the event. Google Workspace add-ons use manifest triggers, defined in the add-on's manifest, to trigger actions like displaying cards on homepage, when opening/updating Calendar events, selecting Drive items, or opening a message in Gmail. Contextual triggers and installable triggers are also supported but with some restrictions.\n"],null,["# Triggers for Google Workspace add-ons\n\n[Apps Script triggers](/apps-script/guides/triggers) cause a specified script\nfunction (the *trigger function*) to execute whenever a specified event\noccurs. Only certain events can cause triggers to fire, and each\nGoogle Workspace application supports a different set of events.\n\nWhen a trigger fires, an *event object* is created. This JSON structure\ncontains details about the event that occurred. The information in the event\nobject structure is organized differently based on the trigger type.\n\nOnce the event object is created, Apps Script passes it as a parameter to the\ntrigger function. The trigger function is a callback function that you must\nimplement yourself, to take whatever actions are appropriate to respond to the\nevent. For example, in a\nGoogle Workspace add-on that extends Gmail, you can\ndefine a trigger that creates a new card interface when the user opens a message\nthread. In this case, you implement a contextual callback function to create\nthe cards making up the new UI using the data passed in the\n[event object](/workspace/add-ons/concepts/event-objects).\n\nThis page provides guidelines on using triggers in\nGoogle Workspace\nadd-on projects.\n\nManifest triggers\n-----------------\n\nUnlike Editor add-ons, Google Workspace add-ons\ncurrently can't use Apps Script [simple triggers](/apps-script/guides/triggers)\nInstead, they use triggers designed specifically for\nGoogle Workspace add-ons: *manifest triggers*.\n\nManifest triggers are defined completely in the\nGoogle Workspace add-on's\n[manifest](/workspace/add-ons/concepts/workspace-manifests). Examples of manifest triggers include the\nfollowing:\n\n- **Homepage triggers** that build and display the add-on homepage.\n- **Calendar eventOpen triggers** that display a new card or take other actions when a Calendar event is opened.\n- **Calendar eventUpdate triggers** that display a new card or take other actions when a user edits and saves a Calendar event.\n- **Drive onItemsSelected triggers** that display a new card or take other actions when a user selects one or more files or folders in Drive.\n- **Gmail compose triggers** that display an add-on card when the user opens the add-on in the Gmail compose window.\n- **Gmail contextual triggers** that display a new card or take other actions when the user opens a Gmail message.\n- **Editor onFileScopeGranted triggers** that display a new card when users grant authorization for the `drive.file` OAuth scope in the current Editor document.\n\nIn the above list, only homepage triggers are non-contextual; the rest are\ncontextual triggers. See [Manifest](/workspace/add-ons/concepts/workspace-manifests)\nfor more information about manifest trigger definitions.\n\nIn addition to manifest triggers, Google Workspace\nadd-ons can also use Apps Script\n[installable triggers](/apps-script/guides/triggers/installable).\n\n### Restrictions\n\nManifest triggers have certain restrictions to their use.\n\n- These triggers are only used in Google Workspace add-on projects; they have no purpose in any other application.\n- Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script [`Script`](/apps-script/reference/script) service to create or modify these triggers.\n- Gmail contextual triggers currently can only have an `unconditional` criteria. This means contextual triggers fire for every email message, regardless of content.\n- Each add-on can only have one trigger of each type, per user, per document."]]
