外掛程式動作可為小工具提供互動行為。建立動作後,您可以定義使用者選取或更新小工具時會發生什麼事。
在多數情況下,您可以使用 Apps Script Card 服務提供的 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 結構,會整理物件包含的資訊。當首頁觸發條件用來建立首頁,或當內容相關觸發條件觸發更新外掛程式顯示畫面時,系統就會使用相同的結構。
如需事件物件結構的完整說明,請參閱事件物件。