本頁面說明如何在資訊卡或對話方塊訊息中新增小工具和 UI 元素,讓使用者能與您的 Google Chat 應用程式互動,例如點選按鈕或提交資訊。
您可以使用 Card Builder 設計及預覽即時通訊應用程式的 JSON 資訊卡訊息:
開啟卡片建構工具先備知識
新增按鈕
ButtonList
小工具會顯示一組按鈕。按鈕可以顯示文字和圖示,或同時顯示文字和圖示。每個 Button
都支援使用者點選按鈕時發生的 OnClick
動作。例如:
針對無障礙功能,按鈕支援替代文字。
新增可執行自訂函式的按鈕
以下資訊卡包含包含兩個按鈕的 ButtonList
小工具。點選一個按鈕,即可在新分頁中開啟 Google Chat 開發人員說明文件。另一個按鈕會執行名為 goToView()
的自訂函式,並傳遞 viewType="BIRD EYE VIEW"
參數。
新增自訂顏色和已停用的按鈕
您可以透過設定 "disabled": "true"
來避免使用者點選按鈕。
以下內容顯示一張資訊卡,由包含兩個按鈕的 ButtonList
小工具組成。其中一個按鈕會使用 Color
欄位自訂按鈕的背景顏色。另一個按鈕已由 Disabled
欄位停用,這會導致使用者無法點選該按鈕並執行函式。
新增有圖示的按鈕
以下顯示由 ButtonList
小工具以及兩個圖示 Button
小工具組成的資訊卡。其中一個按鈕會使用 knownIcon
欄位顯示 Google Chat 的內建電子郵件圖示。另一個按鈕會使用 iconUrl
欄位顯示自訂圖示小工具。
新增含有圖示和文字的按鈕
以下內容顯示包含 ButtonList
小工具的資訊卡,以提示使用者傳送電子郵件。第一個按鈕顯示電子郵件圖示,第二個按鈕則顯示文字。使用者可以按一下圖示或文字按鈕執行 sendEmail
函式。
新增可選取的 UI 元素
SelectionInput
小工具提供一組可選取的項目,例如核取方塊、圓形按鈕、切換按鈕或下拉式選單。您可以使用這個小工具,向使用者收集已定義與標準化的資料。如要向使用者收集未定義的資料,請改用 TextInput
小工具。
SelectionInput
小工具支援建議功能,可協助使用者輸入統一資料和變更期間動作,這些動作會在選項輸入欄位發生變更 (例如使用者選取或取消選取項目) 時執行。Actions
即時通訊應用程式可以接收及處理所選項目的值。如要進一步瞭解如何使用表單輸入,請參閱「接收表單資料」。
本節提供使用 SelectionInput
小工具的資訊卡範例。這些範例使用不同類型的區段輸入:
新增核取方塊
以下顯示一個對話方塊,要求使用者透過使用核取方塊的 SelectionInput
小工具,指定聯絡人是專業或私人聯絡人,還是兩者並用:
新增圓形按鈕
下圖顯示一個對話方塊,要求使用者透過使用圓形按鈕的 SelectionInput
小工具,指定聯絡人是專業或個人:
新增切換鈕
以下顯示一個對話方塊,要求使用者透過使用切換按鈕的 SelectionInput
小工具,指定聯絡人是專業或私人人士,還是兩者並用:
新增下拉式選單
以下對話方塊會顯示對話方塊,要求使用者透過使用下拉式選單的 SelectionInput
小工具,指定聯絡人是專業或個人:
新增複選選單
下圖顯示了對話方塊,要求使用者從複選選單中選取聯絡人:
針對複選選單使用資料來源
本節說明如何使用複選選單填入動態來源 (例如 Google Workspace 應用程式或外部資料來源) 的資料。
Google Workspace 的資料來源
您可以透過 Google Workspace 的下列資料來源,為複選選單填入項目:
- Google Workspace 使用者:您只能填入同一個 Google Workspace 機構中的使用者。
- Chat 聊天室:使用者在複選選單中選取項目,只能查看及選取 Google Workspace 機構中的聊天室。
如要使用 Google Workspace 資料來源,請指定 platformDataSource
欄位。與其他選取輸入類型不同,您可以省略 SectionItem
物件,因為這些選取項目是從 Google Workspace 動態來源取得。
以下程式碼顯示 Google Workspace 使用者的複選選單。如要填入使用者,選項輸入來源會將 commonDataSource
設為 USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
下列程式碼顯示 Chat 聊天室的複選選單。如要填入空格,選項的輸入內容會指定 hostAppDataSource
欄位。複選選單也會將 defaultToCurrentSpace
設為 true
,這會將目前空間設為選單中的預設選取項目:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Google Workspace 以外的資料來源
複選選單也可以填入第三方或外部資料來源的項目。舉例來說,您可以使用複選選單,讓使用者從客戶關係管理 (CRM) 系統中的銷售待開發客戶清單中,選取項目。
如要使用外部資料來源,請使用 externalDataSource
欄位指定從資料來源傳回項目的函式。
如要減少對外部資料來源的要求,您可以在使用者於選單中輸入內容之前,先在複選選單中顯示建議項目。舉例來說,您可以填入最近搜尋的使用者聯絡人。如要從外部資料來源填入建議項目,請指定 SelectionItem
物件。
以下程式碼顯示了來自使用者外部一組聯絡人的複選選單。根據預設,選單會顯示一個聯絡人,並執行 getContacts
函式,以便擷取及填入外部資料來源的項目:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 2,
"externalDataSource": {
"function": "getContacts"
},
"items": [
{
"text": "Contact 3",
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"bottomText": "Contact three description",
"selected": false
}
]
}
}
如果是外部資料來源,您也可以自動完成使用者在複選選單中輸入的項目。舉例來說,如果使用者開始針對填入美國城市的選單輸入 Atl
,Chat 應用程式便可在使用者輸入完畢之前,自動建議 Atlanta
。您最多可以自動完成 100 個項目。
如要自動完成項目,請建立函式來查詢外部資料來源,並在使用者於複選選單中輸入內容時傳回項目。這個函式必須執行以下操作:
- 傳遞代表使用者與選單互動的事件物件。
- 找出互動事件的
invokedFunction
值與externalDataSource
欄位的函式相符。 - 函式相符時,系統會從外部資料來源傳回建議項目。如要根據使用者類型建議項目,請取得
autocomplete_widget_query
鍵的值。這個值代表使用者在選單中輸入的內容。
以下程式碼會自動完成外部資料資源中的項目。在上例中,Chat 應用程式會根據觸發 getContacts
函式的時間來建議項目:
Apps Script
Node.js
新增可讓使用者輸入文字的欄位
TextInput
小工具提供使用者可輸入文字的欄位。小工具支援建議,協助使用者輸入統一資料和保持變更的動作。動作是指在文字輸入欄位發生變更時執行的 Actions
,例如使用者新增或刪除文字。
如果需要收集使用者的抽像或不明資料,請使用這個 TextInput
小工具。如要向使用者收集定義的資料,請改用 SelectionInput
小工具。
如要處理使用者輸入的文字,請參閱「接收表單資料」。
以下是由 TextInput
小工具組成的資訊卡:
讓使用者選擇日期和時間
DateTimePicker
小工具可讓使用者輸入日期、時間,或同時輸入日期和時間。或者,使用者也可以使用挑選器選取日期和時間。如果使用者輸入的日期或時間無效,挑選器會顯示錯誤,提示使用者正確輸入資訊。
如要處理使用者輸入的日期和時間值,請參閱「接收表單資料」。
以下顯示包含三種 DateTimePicker
小工具類型的資訊卡:
驗證輸入至資訊卡的資料
本頁面說明如何驗證已輸入至資訊卡 action
和小工具的資料。舉例來說,您可以驗證文字輸入欄位是否包含使用者輸入的文字,或是否包含特定數量的字元。
設定動作所需的小工具
在資訊卡的 action
中,新增動作需要的小工具名稱至其 requiredWidgets
清單。
叫用這個動作時,如果此處列出的小工具沒有任何值,系統就會取消提交表單動作。
如果為動作設定了 "all_widgets_are_required": "true"
,則此操作需要使用資訊卡中的所有小工具。
在複選功能中設定all_widgets_are_required
動作
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"value": "contact-1",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 1",
"bottomText": "Contact one description",
"selected": false
},
{
"value": "contact-2",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 2",
"bottomText": "Contact two description",
"selected": false
},
{
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 3",
"bottomText": "Contact three description",
"selected": false
},
{
"value": "contact-4",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 4",
"bottomText": "Contact four description",
"selected": false
},
{
"value": "contact-5",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 5",
"bottomText": "Contact five description",
"selected": false
}
]
}
}
]
}
]
}
在 dateTimePicker 中設定 all_widgets_are_required
動作
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
在下拉式選單中設定all_widgets_are_required
動作
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
設定文字輸入小工具的驗證設定
在 textInput
小工具的驗證欄位中,您可以指定這個文字輸入小工具的字元限制和輸入類型。
設定文字輸入小工具的字元限制
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
設定文字輸入小工具的輸入類型
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
疑難排解
當 Google Chat 應用程式或資訊卡傳回錯誤時,Chat 介面會顯示「發生錯誤」的訊息。或「無法處理你的要求」。Chat UI 有時不會顯示任何錯誤訊息,但 Chat 應用程式或資訊卡卻產生非預期的結果,例如資訊卡可能不會顯示。
雖然 Chat UI 可能不會顯示錯誤訊息,但可以在啟用 Chat 擴充應用程式的錯誤記錄功能時,查看描述性的錯誤訊息和記錄資料,協助您修正錯誤。如要瞭解如何查看、偵錯及修正錯誤,請參閱「疑難排解及修正 Google Chat 錯誤」。