Eingabeüberprüfung

In Version 1.3 und höher des Schemas unterstützt AdaptiveCards die clientseitige Eingabeüberprüfung der Eingabetypen.

Validierungseigenschaften

In AdaptiveCards werden die folgenden Eigenschaften für die Überprüfung unterstützt:

Eingabe	Eigenschaften
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

Eine errorMessage-Eigenschaft ist für alle Eingabetypen verfügbar, um anzugeben, welcher Fehler einem Benutzer angezeigt werden soll, wenn ein ungültiger Wert eingegeben wird.

Hinweis

Die Min- und Max-Eigenschaften (einschließlich MaxLength) werden auf einigen Plattformen möglicherweise direkt durch das Steuerelement erzwungen. Beispielsweise kann eine Min-Eigenschaft für Input.Date durchgesetzt werden, um Benutzer in einer Datumsauswahl an der Auswahl eines Datums vor dem frühest möglichen Datum zu hindern. In diesem Fall wird die Fehlermeldung möglicherweise nicht angezeigt.

Bezeichnungen

Eine weitere Eigenschaft, die in Schemaversion 1.3 für alle Eingabeelemente hinzugefügt wurde, ist die label-Zeichenfolgeneigenschaft. Die Verwendung der label -Eigenschaft stellt gegenüber der placeholder-Eigenschaft die empfohlene Methode zum Markieren von Eingaben auf adaptiven Karten dar. Für Verfasser von Karten stellt sie eine einfache und präzise Methode zum Bezeichnen von Eingaben dar und bietet die folgenden Vorteile:

• Überprüfungsindikatoren: Wie oben bereits erwähnt, können Eingaben jetzt als erforderlich markiert werden, und neben Bezeichnungen für Pflichteingaben wird ein visueller Indikator angezeigt. Dieser visuelle Indikator ist in der HostConfig definiert und wird standardmäßig als Sternsymbol * gerendert.
• Barrierefreiheit: Durch die bestehende Verbindung zwischen Bezeichnungen und Eingaben können Rendererbibliotheken die erforderlichen Eigenschaften festlegen, damit Benutzer, die Hilfstechnologien (Bildschirmsprachausgaben) verwenden, ordnungsgemäß mit Eingaben auf adaptiven Karten interagieren können.
  • Bezeichnungen im Vergleich mit Platzhaltern: Wie Katie Sherwin im Artikel Placeholders in form fields are harmful (Platzhalter in Formularfeldern sind gefährlich) erläutert, hat die Verwendung von Platzhaltern viele negative Folgen, etwa die Belastung des Kurzzeitgedächtnisses der Benutzer – was es für Benutzer schwieriger macht, ihre Eingaben vor dem Absenden zu überprüfen –, die schlechte Lesbarkeit, da Platzhaltertext in der Regel schwachen Farbkontrast gegenüber dem Hintergrund aufweist, oder die Tatsache, dass Platzhaltertexte nicht von Bildschirmsprachausgaben gelesen werden, um nur einige zu nennen.
  • TextBlock und RichTextBlock: Die Verwendung anderer Kartenelemente als Bezeichnungen erscheint vielleicht als gute Lösung, sie bietet aber die Schwierigkeit, dass keine Nähe zwischen Eingaben und Bezeichnungen erzwungen werden kann, während bei Verwendung der label-Eigenschaft sichergestellt werden kann, dass beide visuellen Elemente benachbart dargestellt werden, was Benutzern hilft, die Bildschirmlupen benötigen.

Zu überprüfende und zu übermittelnde Felder

Die Eingaben werden überprüft, wenn der Benutzer auf der Karte auf eine Action.Submit-Aktion klickt. Dies sind die Eingaben, die für eine bestimmte Action.Submit-Aktion überprüft und übermittelt werden:

• Eingaben auf der gleichen Karte wie Action.Submit
• Im Fall einer Karte unter einer Action.ShowCard alle Eingaben auf allen übergeordneten Karten der Karte, die Action.Submit enthält

Wenn diese Eingaben die Überprüfung bestehen, werden die Werte in ihren Feldern an den Client zurückgegeben. Wenn sie die Überprüfung nicht bestehen, werden die Fehlermeldungen für die ungültigen Eingaben angezeigt, und die Übermittlung wird nicht gesendet.

Hinweis

Eingaben werden nicht überprüft oder übermittelt, wenn sie sich auf einer Karte befinden, die eine untergeordnete oder gleichgeordnete Karte der Karte ist, die Action.Submit enthält. Dies schließt auch Karten von Action.ShowCards in ActionSets im Textkörper der betreffenden Karte ein. Dieses Verhalten stellt eine Änderung gegenüber Rendererversionen vor 2.0 dar und gilt für alle Karten aller Schemaversionen, unabhängig davon, ob Eigenschaften der Eingabeüberprüfung verwendet werden.

Weitere Überlegungen und bekannte Probleme

• Es ist nicht empfehlenswert, Eingaben mit Überprüfungseigenschaften zu erstellen, die aufgrund von Interaktion mit Action.ToggleVisibility möglicherweise nicht jederzeit sichtbar sind. Fehlermeldungen und visuelle Hinweise, dass eine Eingabe ungültig ist, werden nicht angezeigt, wenn die Eingabe aktuell nicht sichtbar ist, was bei Benutzern zu Verwirrung darüber führen kann, warum ihre Eingabe blockiert wird.

• Das Verhalten der Eingabeüberprüfung für Hosts, die Popup-Anzeigekarten mithilfe des Werts "actions":"showCard":"actionMode":"popup" in ihrer Hostkonfiguration verwenden, ist nicht genau definiert. Popup-Anzeigekarten werden möglicherweise in einer zukünftigen Version als veraltet markiert.