本指南將說明您可能會遇到的常見資訊卡相關錯誤,以及解決方法。
使用資訊卡建構工具設計及預覽資訊卡。
開啟資訊卡建構工具資訊卡錯誤的顯示方式
卡片錯誤資訊清單以多種方式呈現:
- 資訊卡的部分內容 (例如小工具或元件) 不會以非預期的方式顯示或顯示。
- 完整的資訊卡不會顯示。
- 對話方塊關閉、未開啟或載入。
如果您遇到這類行為,表示應用程式的資訊卡發生錯誤。
請參考:正常運作且不含任何錯誤的卡片訊息和對話方塊
在檢查錯誤資訊卡示例之前,請先考慮這張工作資訊卡訊息和對話方塊。為了說明各項範例錯誤及其修正方式,這張資訊卡的 JSON 會因為出現錯誤而修改。
卡片訊息 (未發生錯誤)
以下為有效且不含錯誤的資訊卡訊息,詳細說明含有標題、區段和小工具 (例如裝飾文字和按鈕) 的聯絡資訊:
不含錯誤的對話方塊
以下是有效且不含錯誤的對話方塊,會透過向使用者收集資訊、顯示頁尾,以及文字輸入和切換鈕等可編輯小工具,建立聯絡人:
錯誤:卡片的部分內容未顯示
有時候,資訊卡會正常顯示,但部分資訊卡並未出現,可能原因如下:
- 未填寫必要的 JSON 欄位。
- JSON 欄位有拼字錯誤或大小寫錯誤。
原因:缺少必要的 JSON 欄位
在這個錯誤範例中,缺少必要的 JSON 欄位:title
。因此資訊卡雖然可以顯示,但卡片中應出現的部分卻沒有出現。如省略必填欄位,要預測資訊卡的呈現方式可能並不容易。
如要修正這項錯誤,請新增必要的 JSON 欄位,在本範例中為 title
。
如要瞭解是否需要 JSON 欄位,請參閱資訊卡 v2 參考說明文件。在這個範例中,請參閱 CardHeader
的 title
欄位說明。
請看以下兩個範例:
範例 1:指定 subtitle
但省略必要的 title
,會導致整個標頭顯示為空白:
![這張資訊卡的標題未顯示,因為缺少必填欄位「title」。](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-1.png?authuser=7&hl=zh-tw)
title
」。查看錯誤的資訊卡 JSON 程式碼片段
錯誤:header
缺少必填欄位「title
」。
. . . "header": { "subtitle": "Software Engineer" } . . .
查看正確的資訊卡 JSON 程式碼片段
已修正:必填欄位 title
是 header
規格的一部分。
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer" } . . .
範例 2:指定 subtitle
、imageUrl
、imageType
和 imageAltText
,但省略必要的 title
會導致圖片如預期顯示,但不會產生子標題:
![這張資訊卡的標題未顯示,因為缺少必填欄位「title」。](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-missing-required-entity-header-title-2.png?authuser=7&hl=zh-tw)
title
,但圖片會正常顯示。查看錯誤的資訊卡 JSON 程式碼片段
錯誤:header
缺少必填欄位「title
」。
. . . "header": { "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
查看正確的資訊卡 JSON 程式碼片段
已修正:必填欄位 title
是 header
規格的一部分。
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
原因:JSON 拼字錯誤或大寫
在這個範例中,資訊卡 JSON 包含所有必要欄位,但有一個欄位 imageUrl
的大寫錯誤為 imageURL
(大寫 R
大寫 L
),而這會導致錯誤:其指向的圖片無法顯示。
如要修正這個錯誤和其他類似錯誤,請使用正確的 JSON 格式。在本例中,imageUrl
是正確的。如有疑問,請對照卡片參考文件檢查 JSON 資訊卡。
![這張資訊卡的標題未顯示,因為缺少必填欄位「title」。](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/troubleshoot/troubleshoot-cards-imageURL-instead-of-imageUrl.png?authuser=7&hl=zh-tw)
title
,但圖片會正常顯示。查看錯誤的資訊卡 JSON 程式碼片段
錯誤:imageURL
欄位的大小寫不正確。應為 imageUrl
。
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageURL": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
查看正確的資訊卡 JSON 程式碼片段
修正:imageUrl
欄位的大小寫正確。
. . . "header": { "title": "Sasha", "subtitle": "Software Engineer", "imageUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png", "imageType": "CIRCLE", "imageAltText": "Avatar for Sasha", } . . .
錯誤:無法顯示整張資訊卡
有時卡片本身不會顯示,可能的原因如下:
- 指定不正確的
ButtonList
小工具。 CardFixedFooter
小工具的按鈕指定錯誤。
原因:未正確指定 buttonList
或 cardFixedFooter
如果資訊卡訊息或對話方塊包含錯誤指定的 ButtonList
小工具或 CardFixedFooter
小工具 (有錯誤指定按鈕),整張資訊卡將無法顯示,且在其位置顯示任何內容。錯誤規格可能包括遺漏欄位、拼寫錯誤或大寫欄位,或 JSON 結構不當 (例如缺少半形逗號、引號或大括號)。
如要修正這個錯誤,請對照卡片參考文件檢查卡片 JSON。請進一步比較所有 ButtonList
小工具與 ButtonList
小工具指南。
範例:在 ButtonList
小工具指南中,如果在第一個按鈕中傳遞未完成的 onClick
動作,將導致整張資訊卡無法顯示。
查看錯誤的資訊卡 JSON 程式碼片段
錯誤:onClick
物件未指定任何欄位,因此無法顯示整張資訊卡。
. . . { "buttonList": { "buttons": [ { "text": "Share", "onClick": { } } }, { "text": "Edit", "onClick": { "action": { "function": "goToView", "parameters": [ { "key": "viewType", "value": "EDIT", } ], } } }, ], }, } . . .
查看正確的資訊卡 JSON 程式碼片段
修正:onClick
物件現在包含 openLink
欄位,因此資訊卡可正常顯示。
. . . { "buttonList": { "buttons": [ { "text": "Share", "onClick": { "openLink": { "url": "https://example.com/share", } } }, { "text": "Edit", "onClick": { "action": { "function": "goToView", "parameters": [ { "key": "viewType", "value": "EDIT", } ], } } }, ], }, } . . .
錯誤:對話方塊已關閉、停滯或未開啟
如果對話方塊意外關閉、無法載入或無法開啟,可能是因為卡片介面發生問題。
最常見的原因如下:
CardFixedFooter
小工具沒有primaryButton
。CardFixedFooter
小工具中的按鈕沒有onClick
動作,或是指定onClick
動作不正確。TextInput
小工具缺少name
欄位。
原因:CardFixedFooter
沒有primaryButton
在含有 CardFixedFooter
小工具的對話方塊中,您必須指定同時包含文字和顏色的 primaryButton
。省略 primaryButton
或未正確設定會使整個對話方塊無法顯示。
如要修正這項錯誤,請確認 CardFixedFooter
小工具包含正確的 primaryButton
。
查看錯誤的資訊卡 JSON 程式碼片段
錯誤:fixedFooter
物件未指定 primaryButton
欄位,導致對話方塊無法載入或開啟。
. . . "fixedFooter": { "onClick": { . . . }, "secondaryButton": { . . . } } } . . .
查看正確的資訊卡 JSON 程式碼片段
修正了:fixedFooter
現在指定了 primaryButton
欄位,因此對話方塊可以正常運作。
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { . . . }, "secondaryButton": { . . . } } } . . .
原因:FixedFooter
中的 onClick
設定不正確
在使用 CardFixedFooter
小工具的「對話方塊」中,如有錯誤指定任何按鈕的 onClick
設定或省略此設定,會導致對話方塊關閉、無法載入或未開啟。
如要修正這個問題,請確認每個按鈕都已正確指定 onClick
設定。
查看錯誤的資訊卡 JSON 程式碼片段
錯誤:primaryButton
物件的 onClick
欄位含有拼寫錯誤的「parameters」陣列,導致對話方塊無法載入或開啟。
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { "action": { "function": "setLanguageType", "parrammetters": [ { "key": "languageType", "value": "C++" } ] } } }, "secondaryButton": { "text": "Cancel", "onClick": { "action": { "function": "reset" } } } } . . .
查看正確的資訊卡 JSON 程式碼片段
修正:primaryButton
物件的 onClick
欄位含有正確的拼寫「parameters」陣列,因此對話方塊可以正常運作。
. . . "fixedFooter": { "primaryButton": { "text": "Submit", "color": { "red": 0, "blue": 1, "green": 0 }, "onClick": { "action": { "function": "setLanguageType", "parameters": [ { "key": "languageType", "value": "C++" } ] } } }, "secondaryButton": { "text": "Cancel", "onClick": { "action": { "function": "reset" } } } } . . .
原因:TextInput
沒有name
如果對話方塊中包含排除 name
欄位的 TextInput
小工具,對話方塊會無法正常運作。該網路可能關閉、開啟,但無法載入或無法開啟。
如要修正這項錯誤,請確認每個 TextInput
小工具都含有適當的 name
欄位。確認資訊卡中的每個 name
欄位皆不重複。
查看錯誤的資訊卡 JSON 程式碼片段
錯誤:textInput
物件未指定 name
欄位,導致對話方塊關閉、無法載入或無法開啟。
. . . { "textInput": { "label": "Name", "type": "SINGLE_LINE", } } . . .
查看正確的資訊卡 JSON 程式碼片段
修正了:textInput
現在指定了 name
欄位,因此對話方塊可以正常運作。
. . . { "textInput": { "label": "Name", "type": "SINGLE_LINE", "name": "contactName" } } . . .
使用非同步應用程式架構會導致對話方塊開啟、提交或取消動作失敗
如果 Chat 應用程式在使用對話方塊時傳回錯誤訊息 Could not load dialog. Invalid response returned by bot.
,可能是因為您的應用程式使用非同步的架構 (例如 Cloud Pub/Sub 或 Create Message API 方法)。
開啟、提交或取消對話方塊時,必須使用使用 DialogEventType
的 Chat 應用程式進行同步回應。因此,以非同步架構建構的應用程式不支援對話方塊。
建議您改用資訊卡訊息,而不要使用對話方塊。
其他資訊卡和對話方塊錯誤
如果本頁所述的修正方法無法解決應用程式發生的卡片相關錯誤,請查詢應用程式的錯誤記錄。查詢記錄可協助您找出 JSON 資訊卡或應用程式程式碼中的錯誤,而記錄會包含描述性的錯誤訊息,協助您進行修正。
相關主題
如需修正 Google Chat 應用程式錯誤的相關說明,請參閱疑難排解並修正 Google Chat 應用程式和對 Chat 應用程式進行偵錯。