本頁說明如何在資訊卡或對話方塊訊息中新增小工具和 UI 元素,讓使用者能夠與 Google Chat 應用程式互動,例如點選按鈕或提交資訊。
使用資訊卡建構工具設計及預覽 Chat 應用程式的 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 UI 可能不會顯示錯誤訊息,但我們提供描述性的錯誤訊息和記錄資料,協助您修正啟用 Chat 應用程式錯誤記錄功能時發生的錯誤。如要瞭解如何查看、偵錯及修正錯誤,請參閱「疑難排解及修正 Google Chat 錯誤」。