輸入驗證

在結構描述的 1.3 版和更新版本中，AdaptiveCards 支援輸入類型的用戶端輸入驗證。

驗證屬性

下列屬性支援 AdaptiveCards 中的驗證：

輸入	屬性
Input.ChoiceSet	isRequired
Input.Date	isRequired min max
Input.Number	isRequired min max
Input.Text	isRequired regex maxLength
Input.Time	isRequired min max
Input.Toggle	isRequired

所有輸入類型都可以使用 errorMessage 屬性，以指定當使用者輸入不正確值時應該顯示的錯誤。

注意

有些平台上的 Min 和 Max 屬性 (包括 maxLength) 可能會直接由控制項強制執行。 例如，不允許使用者在日期選擇器選取最小值之前的日期，即可強制執行 Input.Date 的最小值屬性。 在這種情況下，可能不會顯示錯誤訊息。

標籤

針對所有輸入元素在結構描述版本 1.3 中新增的另一個屬性是 label 字串屬性。 使用 label 屬性是在調適型卡片中標記輸入的建議方式 (相較於 placeholder 屬性)。 這是一種簡單明瞭的方式，可為卡片作者標記輸入，並具備下列優點：

• 驗證指標：如先前所述，輸入現在可以標示為必要，必要輸入的標籤旁邊會有視覺指標。 此視覺指標定義於 HostConfig，而且預設會轉譯為星號 *。
• 協助工具：藉由在標籤與輸入之間建立連線，轉譯器程式庫可以設定必要的屬性，讓使用輔助技術 (螢幕助讀程式) 的使用者能夠正確地與調適型卡片內的輸入互動。
  • 標籤與預留位置：如 Katie Sherwin 在表單欄位中的預留位置是有害的一文中所述，使用預留位置有許多負面後果，例如用盡使用者的短期記憶體，讓使用者更難以在提交之前驗證其輸入，讓使用者難以進行閱讀，因為預留位置文字與其背景或螢幕助讀程式的色彩對比通常不佳，而無法讀取預留位置文字 (僅舉幾個為例)。
  • TextBlock 和 RichTextBlock：雖然使用其他卡片元素作為標籤似乎是不錯的解決方式，但卻出現無法在輸入與標籤之間強制鄰近性的問題，而另一方面，藉由使用 label 屬性，我們可確保這兩個視覺效果元素在彼此旁邊轉譯，以協助需要螢幕放大鏡的使用者。

要驗證和提交的欄位

當使用者按一下卡片中的 Action.Submit 動作時，將會驗證輸入。 將會針對指定的 Action.Submit 動作進行驗證和提交的輸入如下：

• 與 Action.Submit 相同卡片上的輸入
• 卡片的任何父代卡片上的輸入，而其在 Action.ShowCard 之下的卡片案例中包含 Action.Submit

如果這些輸入通過驗證，其欄位中的值將會傳回用戶端。 如果未通過驗證，則會顯示無效輸入的錯誤訊息，而且不會傳送提交。

注意

如果輸入所在的卡片是包含 Action.Submit 之卡片的子系或同層級卡片，則不會 驗證或提交輸入。 這包括來自該卡片本文中 ActionSets 中 Action.ShowCards 的卡片。 這是在 2.0 之前轉譯器版本中的行為變更，而且不論是否使用輸入驗證屬性，都適用於所有結構描述版本的卡片。

其他考量和已知問題

• 不建議使用因為與 Action.ToggleVisibility 互動而不一定可見的驗證屬性來建立輸入。 如果目前看不到輸入，將不會顯示輸入無效的錯誤訊息和視覺指示，這可能會讓使用者對其提交遭到封鎖的原因造成混淆。

• 使用快顯顯示使用快顯的主機的輸入驗證行為，並不妥善地定義其主機配置中的 "actions":"showCard":"actionMode":"popup" 值。 快顯顯示卡片可能會在未來的版本中淘汰。