外掛程式動作

外掛程式動作可提供互動行為， 小工具。 建立動作後，您可以定義使用者選取或更新時會發生什麼事 就可以快速生成圖片

在大部分情況下，您可透過 Action敬上 物件。 每個 Action 都與 回呼函式。實作回呼函式 讓使用者在與小工具互動時採取所需的步驟您還必須 將 Action 連結至小工具 使用適當的小工具處理常式函式 定義觸發 Action 回呼。

使用 Action 設定小工具 按照以下一般程序操作：

1. 建立 Action 物件。 並指定要在容器中執行的回呼函式 以及必要的參數
2. 呼叫適當的小工具處理常式函式 透過 Action 顯示小工具 物件。
3. 實作回呼函式以執行必要行為。

，瞭解如何調查及移除這項存取權。

注意： 請勿混淆 Action 含有 CardAction 的物件 如需儲存大量結構化物件 建議使用 Cloud BigtableCardAction 物件 是資訊卡標題選單項目，Action 物件則會定義使用者與 UI 互動時的回應。

小工具處理常式函式

如何將小工具連結至特定 Action 就可以用小工具 處理常式函式。處理常式函式可決定互動類型 (例如，按一下小工具或編輯文字欄位) 會觸發 動作行為處理常式函式也會定義 UI 採取的步驟 在動作完成後產生任何快訊

下表列出小工具的各種處理常式類型以及 搭配使用的小工具：

處理常式函式	觸發動作	適用的小工具	說明
setOnChangeAction()	小工具的值有所變更	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	可設定 Action 這個外掛程式能在小工具失去焦點時，執行 Apps Script 函式，例如 例如使用者在輸入中輸入文字，然後按下 Enter 鍵 處理常式會自動傳遞 事件物件給它呼叫的函式。 您可以在這個事件物件中插入額外參數資訊 可以視需要使用
setOnClickAction()	使用者點選小工具	CardAction Image ImageButton DecoratedText TextButton	可設定 Action 會在使用者點擊小工具時執行 Apps Script 函式。 處理常式會自動傳遞 事件物件給它呼叫的函式。 您可以在這個事件物件中插入選用參數資訊。
setComposeAction()	使用者點選小工具	CardAction Image ImageButton DecoratedText TextButton	Gmail 專用。可設定 Action 這個工具可以建立電子郵件草稿，然後將草稿 Gmail UI 撰寫視窗。草稿可建立為新訊息，或是建立 回覆 Gmail 中開啟的郵件。當處理常式呼叫 就會傳送 事件物件新增至回呼函式。 詳情請見 撰寫訊息草稿 ，掌握更多詳細資訊。
setOnClickOpenLinkAction()	使用者點選小工具	CardAction Image ImageButton DecoratedText TextButton	可設定 Action 使用者點擊小工具時開啟網址在下列情況下，請使用這個處理常式： 建構網址，或在連結前執行其他動作 開啟；否則，使用 setOpenLink() 通常更簡單。 你只能在新視窗中開啟網址。關閉分頁後 用於重新載入外掛程式的 UI。
setOpenLink()	使用者點選小工具	CardAction Image ImageButton DecoratedText TextButton	當使用者按一下小工具時，直接開啟網址。使用這份草稿 處理常式；如果您知道網址，只需要開啟它即可；否則請使用 setOnClickOpenLinkAction()。 您可以在新視窗或重疊視窗中開啟網址。關閉後， 可能會導致使用者介面重新載入外掛程式。
setSuggestionsAction()	使用者在輸入內容中輸入文字	TextInput	可設定 Action 這個 API 會在使用者輸入文字時，執行 Apps Script 函式 文字輸入小工具處理常式會自動傳遞 事件物件給它呼叫的函式。 詳情請見 自動完成建議 以瞭解詳情

回呼函式

當 Action 觸發事件因為回呼函式是 Apps Script 函式，所以 幾乎所有指令碼函式都能執行

警告： Apps Script Card 服務 將回呼函式的執行時間限制在 30 秒內。如果 執行時間超過 30 分鐘，您的外掛程式 UI 可能不會 資訊卡能正確顯示，以回應 Action。

回呼函式有時會傳回特定的回應物件。這些 代表必須在回應類型之後，再進行額外的作業 回呼執行完畢，例如顯示新卡片或進行簡報 自動完成建議。回呼函式必須傳回特定的 回應物件，可以在卡片服務中使用建構工具類別 來建構該物件

下表列出回呼函式必須在何時傳回 特定回應物件。這些動作全部 不受外掛程式擴充的特定代管應用程式影響：

已嘗試操作	回呼函式應傳回
瀏覽資訊卡	ActionResponse
顯示 Notification	ActionResponse
使用 setOnClickOpenLinkAction() 開啟連結	ActionResponse
顯示自動完成建議	SuggestionResponse
使用通用動作	UniversalActionResponse
其他動作	Nothing

除了這些動作之外，每個主機應用程式都有一套專屬的 只能由該主機執行的操作。詳情請參閱下列資源： 指南：

• 日曆動作
• 鼓勵採取行動
• Gmail 動作
• 編輯者動作

，瞭解如何調查及移除這項存取權。

注意： 使用回應建構工具類別時，請務必呼叫 build() 以 產生回應物件否則會導致發生錯誤。

注意： 通用動作的定義 ，而且不需要 Action 物件的回呼函式必須傳回 UniversalActionResponse。

動作事件物件

當外掛程式觸發 Action 時， UI 會自動建構 JSON 事件物件，並將其做為 Action 回呼的引數 函式。此事件物件包含使用者目前的相關資訊 例如，您可以看到 小工具。

動作事件物件具有特定的 JSON 結構， 所含的私密資訊如果 首頁觸發條件 觸發建立首頁，或 內容相關觸發條件 來更新外掛程式顯示畫面。

如需完整的事件物件，請參閱事件物件 事件物件結構的說明。

注意： Gmail 外掛程式採用了簡化版的事件物件結構， 但目前已淘汰以回溯相容於 新事件中仍包含 Gmail 外掛程式事件物件欄位 物件結構 (請參閱事件物件結構)。 不過，同樣的資訊 常見事件 和 Gmail 事件 物件子結構如果您是將 Gmail 外掛程式升級到 Google Workspace 外掛程式，那麼您應該調整程式碼 使用更新過的事件物件欄位，也就是原本的 Gmail 事件物件欄位則會遭到移除。