外掛程式動作

外掛程式動作可為小工具提供互動行為。透過建立動作，您可以定義使用者選取或更新小工具時採取的動作。

在多數情況下，您可以使用 Apps Script Card 服務提供的 Action 物件定義外掛程式動作。在您建立每個 Action 時，每個回呼函式都會與回呼函式相關聯。您可以實作回呼函式，在使用者與小工具互動時採取所需步驟。您也必須使用適當的小工具處理常式函式，將 Action 連結到小工具，藉此定義哪種互動觸發 Action 回呼。

使用以下一般程序，為含有 Action 的小工具設定：

1. 建立 Action 物件，指定應執行的回呼函式以及該物件所需的任何參數。
2. 使用 Action 物件，在小工具上呼叫適當的小工具處理常式函式。
3. 實作回呼函式來代表必要行為。

注意： 請勿將 Action 物件與 CardAction 物件混淆。CardAction 物件是資訊卡標題選單項目，Action 物件則會定義使用者與 UI 互動的回應。

小工具處理常式函式

如要將小工具連結至特定 Action 或其他行為，請使用小工具處理常式函式。處理常式函式會判斷哪種互動類型 (例如按一下小工具或編輯文字欄位) 會觸發動作行為。處理常式函式也會定義 UI 在動作完成後採取的步驟 (如果有的話)。

下表列出了小工具的不同處理常式類型，以及它們搭配使用的小工具：

處理常式函式	觸發動作	適用的小工具	說明
setOnChangeAction()	小工具值會隨之變更	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	設定在小工具遺失焦點時執行 Apps Script 函式的 Action，例如使用者輸入內容並按下 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()。您可以在新視窗或重疊視窗中開啟網址。關閉後，可能會導致 UI 重新載入外掛程式。
setSuggestionsAction()	使用者在輸入內容中輸入文字	TextInput	設定 Action，當使用者在文字輸入小工具中輸入文字時，就會執行 Apps Script 函式。處理常式會自動將事件物件傳遞至自身呼叫的函式。詳情請參閱文字輸入的自動完成建議。

回呼函式

回呼函式會在 Action 觸發時執行。回呼函式是 Apps Script 函式，因此幾乎所有指令碼函式都能執行任何功能。

警告： Apps Script Card 服務將回呼函式限制在執行時間最長為 30 秒。如果執行時間過長，外掛程式 UI 可能無法為回應 Action 正確更新資訊卡顯示畫面。

回呼函式有時會傳回特定的回應物件。這類回應表示回呼執行完畢後需要執行的其他作業，例如顯示新卡片或顯示自動完成建議。當回呼函式必須傳回特定回應物件時，您可以使用卡片服務中的建構工具類別來建構該物件。

下表列出回呼函式必須針對特定動作傳回特定回應物件的時機。這些動作都不受外掛程式擴充的特定主機應用程式影響：

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

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

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

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

注意： 通用動作是在專案資訊清單中定義，因此不需要 Action 物件，但其回呼函式必須傳回 UniversalActionResponse。

動作事件物件

當外掛程式觸發 Action 時，UI 會自動建構 JSON 事件物件，並將其做為引數傳送至 Action 回呼函式。這個事件物件包含使用者目前用戶端內容的相關資訊，例如顯示資訊卡中所有互動式小工具的目前值。

動作事件物件具有特定的 JSON 結構，用來整理其中包含的資訊。當首頁觸發條件啟動建立首頁，或觸發內容相關觸發條件來更新外掛程式的功能時，系統就會採用相同的結構。

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

注意： Gmail 外掛程式使用的是這個事件物件結構的簡化版本，現已淘汰。為了回溯相容，新的 Gmail 外掛程式事件物件欄位仍包含在新事件物件結構中 (請參閱事件物件結構)。不過，系統會在常見事件和 Gmail 事件物件子結構中重現相同的資訊。如果您要將 Gmail 外掛程式升級為 Google Workspace 外掛程式，應調整程式碼以使用更新的事件物件欄位，最後將移除原本的 Gmail 事件物件欄位。