外掛程式動作

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

在大多數情況下，您可以使用 Google 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 		設定 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。您可以在新視窗或疊加層中開啟網址。關閉時，您可以讓 UI 重新載入外掛程式。
setSuggestionsAction 使用者在輸入內容中輸入文字 TextInput 設定 Action，在使用者於文字輸入小工具中輸入文字時，執行 Apps Script 函式。處理常式會自動將事件物件傳遞至呼叫的函式。詳情請參閱「文字輸入的自動完成建議」。

回呼函式

當 Action 觸發時，系統會執行回呼函式。由於回呼函式是 Apps Script 函式，因此幾乎可以執行任何其他指令碼函式可以執行的動作。

回呼函式有時會傳回特定回應物件。這類回應表示回呼函式執行完畢後，還需要進行其他作業，例如顯示新資訊卡或呈現自動完成建議。如果回呼函式必須傳回特定回應物件，請使用 Card 服務中的建構工具類別建構該物件。

下表顯示回呼函式必須針對特定動作傳回特定回應物件的時間。這些動作全都與外掛程式擴充的特定主機應用程式無關：

嘗試執行的動作 回呼函式應會傳回
導覽 ActionResponse
顯示 Notification ActionResponse
使用 setOnClickOpenLinkAction 開啟連結 ActionResponse
顯示自動完成建議 SuggestionResponse
使用通用動作 UniversalActionResponse
其他動作 Nothing

Google Workspace 主機應用程式的動作

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

使用回覆建構工具類別時，請呼叫 build 方法來產生回覆物件。否則會發生錯誤。

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

動作事件物件

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

動作事件物件具有特定 JSON 結構，可整理所含資訊。當首頁觸發條件觸發以建立首頁，或情境觸發條件觸發以更新外掛程式顯示畫面時，系統會使用相同的結構。

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

Gmail 外掛程式使用簡化版的事件物件結構，但這項功能已淘汰。為確保回溯相容性，所有原始 Gmail 外掛程式事件物件欄位仍會包含在新的事件物件結構中 (請參閱事件物件結構)。不過，相同的資訊會重現在 commonEventObject 和 Gmail event 物件的子結構中。如果將 Gmail 外掛程式升級為 Google Workspace 外掛程式，請調整程式碼，使用更新的事件物件欄位。原始 Gmail 活動物件欄位最終會遭到移除。