外掛程式動作可為小工具提供互動行為。透過建立動作,您可以定義使用者選取或更新小工具時採取的動作。
在多數情況下,您可以使用 Apps Script Card 服務提供的 Action
物件定義外掛程式動作。在您建立每個 Action
時,每個回呼函式都會與回呼函式相關聯。您可以實作回呼函式,在使用者與小工具互動時採取所需步驟。您也必須使用適當的小工具處理常式函式,將 Action
連結到小工具,藉此定義哪種互動觸發 Action
回呼。
使用以下一般程序,為含有 Action
的小工具設定:
小工具處理常式函式
如要將小工具連結至特定 Action
或其他行為,請使用小工具處理常式函式。處理常式函式會判斷哪種互動類型 (例如按一下小工具或編輯文字欄位) 會觸發動作行為。處理常式函式也會定義 UI 在動作完成後採取的步驟 (如果有的話)。
下表列出了小工具的不同處理常式類型,以及它們搭配使用的小工具:
處理常式函式 | 觸發動作 | 適用的小工具 | 說明 |
---|---|---|---|
setOnChangeAction() |
小工具值會隨之變更 |
DatePicker DateTimePicker SelectionInput Switch TextInput
TimePicker
|
設定在小工具遺失焦點時執行 Apps Script 函式的 Action ,例如使用者輸入內容並按下 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 函式,因此幾乎所有指令碼函式都能執行任何功能。
回呼函式有時會傳回特定的回應物件。這類回應表示回呼執行完畢後需要執行的其他作業,例如顯示新卡片或顯示自動完成建議。當回呼函式必須傳回特定回應物件時,您可以使用卡片服務中的建構工具類別來建構該物件。
下表列出回呼函式必須針對特定動作傳回特定回應物件的時機。這些動作都不受外掛程式擴充的特定主機應用程式影響:
已嘗試執行動作 | 回呼函式應會傳回 |
---|---|
瀏覽資訊卡 | ActionResponse |
顯示 Notification |
ActionResponse |
使用 setOnClickOpenLinkAction() 開啟連結 |
ActionResponse |
顯示自動完成建議 | SuggestionResponse |
使用通用動作 | UniversalActionResponse |
其他動作 | 無 |
除了這些動作之外,每個主機應用程式都有一組專屬動作,只能在該主機中執行。詳情請參閱下列指南:
動作事件物件
當外掛程式觸發 Action
時,UI 會自動建構 JSON 事件物件,並將其做為引數傳送至 Action
回呼函式。這個事件物件包含使用者目前用戶端內容的相關資訊,例如顯示資訊卡中所有互動式小工具的目前值。
動作事件物件具有特定的 JSON 結構,用來整理其中包含的資訊。當首頁觸發條件啟動建立首頁,或觸發內容相關觸發條件來更新外掛程式的功能時,系統就會採用相同的結構。
如需事件物件結構的完整說明,請參閱事件物件。