外掛程式動作

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

在大多數情況下，您可以使用 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 指令碼函式，例如使用者在輸入框中輸入文字並按下 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 時，正確更新卡片顯示畫面。

回呼函式有時會傳回特定回應物件。這類回應表示在回呼完成執行後，需要執行其他作業，例如顯示新資訊卡或提供自動完成建議。如果回呼函式必須傳回特定回應物件，您可以在 Card 服務中使用建構函式類別建構該物件。

下表說明回呼函式必須在何時針對特定動作傳回特定回應物件。這些動作都與外掛程式要延伸的特定主機應用程式無關：

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

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

• 日曆動作
• 雲端硬碟動作
• Gmail 動作
• 編輯器動作

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

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

動作事件物件

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

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

如要進一步瞭解事件物件結構，請參閱「事件物件」。

注意： Gmail 外掛程式使用的是這個事件物件結構的簡化版本，但現在已淘汰。為確保回溯相容性，所有原始 Gmail 外掛程式事件物件欄位仍包含在新事件物件結構中 (請參閱「事件物件結構」)。不過，通用事件和 Gmail 事件 物件子結構體會重現相同資訊。如果您要將 Gmail 外掛程式升級為 Google Workspace 外掛程式，請調整程式碼，以便使用更新後的事件物件欄位，原始的 Gmail 事件物件欄位最終會遭到移除。