本頁面由 Cloud Translation API 翻譯而成。

外掛程式動作

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

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

請按照下列一般程序，設定含有 Action 的小工具：

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

小工具處理常式函式

如要將小工具連結至特定 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 函式，因此您可以讓回呼函式執行其他指令碼函式幾乎所有功能。

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

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

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

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

動作事件物件

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

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

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