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

外掛程式動作

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

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

請使用下列一般程序透過 Action 設定小工具：

建立 Action 物件，指定該物件要與它需要的所有參數一起執行的回呼函式。
使用 Action 物件，對小工具呼叫適當的小工具處理常式函式。
實作回呼函式以執行必要行為。

小工具處理常式函式

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

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

處理常式函式	觸發動作	適用的小工具	說明
`setOnChangeAction()`	小工具的值有所變更	`DatePicker` `DateTimePicker` `SelectionInput` `Switch` `TextInput` `TimePicker`	設定 `Action`，在小工具失去焦點時 (例如使用者在輸入並按下 Enter 鍵)，執行 Apps Script 函式。這個處理常式會自動將事件物件傳遞至其呼叫的函式。如有需要，您可以在這個事件物件中插入額外參數資訊。
`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()` 通常較為簡單。你只能在新視窗中開啟網址。關閉後，使用者介面可能會重新載入外掛程式。
`setOpenLink()`	使用者點選小工具	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	當使用者按一下小工具時，直接開啟網址。如果知道網址，且只需要開啟此處理常式，請使用這個處理常式；否則請使用 `setOnClickOpenLinkAction()`。您可以在新視窗或重疊視窗中開啟網址。關閉後，使用者介面可能會重新載入外掛程式。
`setSuggestionsAction()`	使用者在輸入內容中輸入文字	`TextInput`	設定 `Action`，當使用者在文字輸入小工具中輸入文字時，執行 Apps Script 函式。處理常式會自動將事件物件傳遞至其呼叫的函式。詳情請參閱「文字輸入的自動完成建議」。

回呼函式

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

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

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

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

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

動作事件物件

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

動作事件物件有特定的 JSON 結構，會整理物件包含的資訊。當首頁觸發條件用來建立首頁，或當內容相關觸發條件觸發更新外掛程式顯示畫面時，系統就會使用相同的結構。

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