Text field

Die Textfeld-Komponente ermöglicht dem Nutzer Text oder numerische Werte einzugeben.

Overview

Intro

Das Text field ermöglicht dem Nutzer Text oder numerische Werte einzugeben. Es ist auf einzeilige Texteingaben ausgerichtet; für mehrzeilige Eingaben gibt es die eigene Komponente Text Area . Eingaben mit besonderer Schreibweise werden über ein entsprechend konfiguriertes maskiertes Text field bereitgestellt. Text- bzw. alphanumerische Eingaben sind immer unformatiert, d. h. die reine Zeichenfolge wird erfasst.

Ein Eingabefeld sollte immer einen klaren Zweck haben, der als Label angezeigt wird (z.B. Name, Straße, PLZ, Stadt, IBAN, Telefonnummer, etc.)

broken_image

Figma

Text Field

Verwendung

👍 Do

👎 Don't

Verwenden wenn: - eine Erfassung von Daten in Form von Freitext oder alphanumerischen Eingaben in Formularen erfolgt. - kurze einzeilige Daten erfasst werden müssen.

Nicht verwenden wenn: - nur ein einfacher Anzeigetext (z. B. Textblöcke, Absätze) dargestellt werden soll. Hierfür gibt es verschiedene Textformatierungen die Sinn machen können (siehe Typografie). - das Standard Eingabefeld sich in einem Fließtext befinden würde (→ nicht im Fließtext verwenden) - es eine bestimmte Anzahl an vordefinierten Optionen zur Eingabe gibt. Hierfür ein Dropdown oder eine ComboBox verwenden. - eingegebene Daten angezeigt werden sollen, verwende dazu Name-Wert-Facetten . - die Eingabe vom Nutzer geregelt werden muss, verwende dazu das maskierte Text field. - die Nutzer Daten in bestimmten Formaten wie z.B. Geldbeträge mit Tausenderpunkten, Kreditkartennummern, IBAN oder IP Adressen eingeben sollen, verwende dazu das maskierte Text field. - längere Texteingaben nötig sind, verwende dazu die Text Area . - Passwörter eingegeben werden sollen, verwende dazu das Password Field . - eine E-Mail-Adresse erfasst werden soll, verwende dazu das Email Field . - ein numerischer Wert schrittweise angepasst werden soll, verwende dazu das Number Field .

Guidelines

Aufbau

Das Text field setzt sich aus folgenden Bestandteilen zusammen. Label und Eingabefeld sind immer vorhanden, die als optional gekennzeichneten Elemente werden nur bei Bedarf ergänzt:

• Label — kennzeichnet das Feld. Für die Barrierefreiheit erforderlich. Unterstützt Plaintext-Inhalt; die Länge ist durch die Breite des Feldes begrenzt.
• Eingabefeld — nimmt den Wert auf, den der Nutzer eintippt. Es ist einzeilig; für mehrzeilige Eingaben ist die Text Area vorgesehen.
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um Formatanforderungen oder den Zweck des Feldes zu erläutern. Eine Style-Variante erlaubt die Darstellung oberhalb des Feldes.
• Placeholder (optional) — wird angezeigt, solange das Feld leer ist. Er ist nur zu verwenden, wenn kein Helper text möglich ist, ersetzt kein sichtbares Label und kann für einen bereits eingegebenen Wert gehalten werden.
• Tooltip (optional) — kleines Text-Pop-up, das bei Hover und bei Tastatur-Fokus angezeigt wird. Helper werden gegenüber Tooltips generell bevorzugt, da sie besser auffindbar und mobil besser unterstützt sind.
• Prefix und Suffix (optional) — Elemente an den Enden des Feldes, geeignet für Einheiten, Symbole oder Icons. Screenreader lesen sie in der Regel nicht zuverlässig vor; die Information muss zusätzlich über Label, Helper text oder ARIA verfügbar sein.
• Clear button (optional) — erscheint, sobald das Feld nicht leer ist, und löscht den aktuellen Wert. Der Button selbst ist nicht tastaturfokussierbar; bei fokussiertem Feld löscht die Escapetaste den Wert. Nützlich ist er vor allem in Such- und Filterfeldern, in regulären Formularen weniger.
• Required indicator (bei Bedarf) — Pflichtfelder werden durch einen Indikator neben dem Label gekennzeichnet. Die Kennzeichnung und ihre Erläuterung regelt Formulare .

Die Anordnung des Feldes im Formular und seine Spaltenbelegung regelt das Form Layout .

Info für Dev

In Web Components hat jedes Eingabefeld ein eigenes Paket und ein eigenes Element: @vaadin/text-field, @vaadin/text-area, @vaadin/email-field, @vaadin/password-field und @vaadin/number-field. Alle fünf sind in @mate/bundles enthalten.

In Vue liegt ebenfalls jedes Feld in einem eigenen Paket: @mate-vue/text-field, @mate-vue/text-area, @mate-vue/email-field, @mate-vue/password-field und @mate-vue/number-field, mit den Komponenten MateTextField, MateTextArea, MateEmailField, MatePasswordField und MateNumberField.

In Flow stammen alle Klassen aus einem einzigen Maven-Artefakt vaadin-text-field-flow und dem Paket com.vaadin.flow.component.textfield. Jede Klasse wird trotzdem einzeln importiert.

Anordnung & Gruppierung

Links ausrichten (Standard)

Die Textausrichtung innerhalb der Textfelder ist standardmäßig linksbündig. Dadurch stehen das Label und der Wert räumlich und visuell nah beieinander, was das Erfassen der Eingabefelder für den Nutzer erleichtert.

broken_image

Figma

Standard Textfeld

Rechts ausrichten

Zahlenwerte wie Währungen oder Maßeinheiten für Flächen und Volumen wie ㎡ oder Kubik Liter darstellen, müssen rechtsbündig ausgerichtet werden. Datum und Uhrzeit Werte bleiben davon unberührt und müssen weiterhin linksbündig dargestellt werden.

broken_image

Figma

Text field mit rechtsbündigem Wert

Währungen und sonstige Einheiten

Währungen und Einheiten sind als Suffix umzusetzen. Damit lässt sich der Wert von der Einheit besser trennen. Dadurch werden Validierungen vereinfacht und die Eingabe für den Nutzer ist einheitlich geregelt. 

Varianten/ Typen

Standard Text field

broken_image

Figma

Standard Text field

Maskiertes Text field

Info für Dev

Die Maskierung erfolgt über die Format Utilities aus dem Paket @mate/format. Es ist in @mate/bundles enthalten und stellt die Funktionen number, masked, phone und dateFormat bereit; IBAN und Kreditkartennummern werden über masked abgebildet.

Maskierte Text fields regeln, was Nutzer in das Text field eingeben können. Sie erleichtern den Nutzern die Eingabe in bestimmten Formaten. Zu diesen zählen z.B. Geldbeträge mit Tausenderpunkten, Kreditkartennummern, IBAN oder IP Adressen.

broken_image

Figma

Maskiertes Textfeld

Das Mate Design System bietet folgende häufig genutzte Utilities für die Maskierung beim Text Field

• Numerische Werte mit Tausenderpunkten
• IBAN
• Kreditkartennummern
• Telefonnummern
• Uhrzeiten

Platzhalter Text

Der Platzhalter-Text kann verwendet werden, um das erwartete Format an den Nutzer zu kommunizieren. Sobald ein Zeichen eingegeben wird, verschwindet der Platzhalter-Text.

Formatierung

Die Formatierung in einem maskierten Eingabefeld erfolgt direkt während der Eingabe.

Die Formatierung kann dynamisch auf die Werte, die eingegeben werden, reagieren. So können die Formatierungen z.B. je nach Kreditkarten-Anbieter variieren.

Kreditkarten-Anbieter	Format
American Express	#### ###### #####
VISA	#### #### #### ####

Werte kopieren

Werte, die aus einem maskierten Eingabefeld kopiert werden, enthalten die Formatierung.

Wert im maskierten Eingabefeld	Wert im Zwischenspeicher
16:54:21	16:54:21
1.234,56	1.234,56

Wert einfügen

Nutzer können formatierte und unformatierte Werte in ein maskiertes Eingabefeld einfügen.

Quelle die Nutzer kopieren	Wert im maskierten Eingabefeld, nach dem Einfügen
4000-1234-1234-1234	4000 1234 1234 1234
4000123412341234	4000 1234 1234 1234

Verhalten

Bei Klick in ein Eingabefeld, wird der Cursor in dieses gesetzt und der Nutzer kann die Eingabe beginnen. Je nach Typ des Eingabefeldes (z.B. numerische Eingabe) können bestimmte Eingaben verboten werden. So wird die Häufigkeit von Fehleingaben verringert.

Validierung

Die Validierung erfolgt, wenn der Nutzer eine Wertänderung auslöst, z.B. durch Eingabe und Drücken von "Enter". Spätestens beim Verlassen des Feldes wird geprüft, auch wenn der Wert unverändert geblieben ist. Ist der Wert ungültig, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes.

Die Prüfung läuft in zwei Stufen. Die Pre-Submit-Validierung prüft das einzelne Feld, sobald es den Fokus verliert, und zeigt den Fehler unmittelbar unterhalb des Feldes. Die Post-Submit-Validierung läuft, nachdem der Nutzer das Formular abgeschickt hat: Sie prüft alle Felder erneut, markiert die fehlerhaften und setzt den Fokus auf das erste davon. Beide Stufen und die Formulierung der Fehlermeldungen sind unter Validierung unter Formulare beschrieben.

Folgende Constraints werden unterstützt:

Constraint	Verhalten
Required	Das Feld wird ungültig, wenn der Wert zunächst eingegeben und anschließend gelöscht wird.
Min / Max length	Legt die kleinste und die größte Anzahl an Zeichen fest, die das Feld akzeptiert. Eine zu kurze Eingabe macht das Feld ungültig, die Eingabe wird auf die maximale Länge begrenzt.
Pattern	Ein regulärer Ausdruck, gegen den der vollständige Wert geprüft wird. Ein Wert, der dem Muster nicht vollständig entspricht, macht das Feld ungültig.
Allowed characters	Ein regulärer Ausdruck für einzelne Zeichen kann einschränken, welche Zeichen eingegeben werden dürfen. Zeichen, die nicht dem Ausdruck entsprechen, werden abgewiesen. Programmatisch gesetzte Werte unterliegen dieser Einschränkung nicht.

Jedes Constraint sollte eine eigene Fehlermeldung haben, damit der Nutzer spezifisches, umsetzbares Feedback erhält.

States

Ein Eingabefeld im State Enabled kann vom Nutzer fokussiert werden und die Eingabe kann wie gewohnt erfolgen.

Die Darstellung der States Enabled , Disabled , Read Only , Hover und Focus entspricht der Standarddarstellung. Siehe States .

Error

Eingabefelder können validiert werden. Je nach Ergebnis der Validierung wird das Eingabefeld hervorgehoben. Im State Error erscheint die Fehlermeldung unterhalb vom Eingabefeld und das Feld wird rot hervorgehoben. Die Fehlermeldung sollte so formuliert werden, dass dem Nutzer klar ist, wie der entstandene Validierungsfehler behoben werden kann, siehe dazu auch Validierung unter Formulare .

Hilfetext

Wenn nötig, kann unterhalb des Eingabefeldes ein Hilfetext angezeigt werden. Dieser gibt dem Nutzer weitere Informationen über die benötigte Eingabe.

Barrierefreiheit

Tastaturbedienung

Über die Tabulatortaste ("Tab") oder Hochstell- und Tabulatortaste ("Shift" + "Tab") lässt sich zwischen den einzelnen Eingabefeldern springen. In einem fokussierten Eingabefeld im State Enabled kann die Eingabe wie gewohnt erfolgen.

Ist ein Clear button vorhanden, ist er selbst nicht fokussierbar. Bei fokussiertem Feld löscht die Escapetaste ("Esc") den Wert.

Spezifische Hinweise

Die Komponente stellt selbst bereit: die Verknüpfung des sichtbaren Labels mit dem Eingabefeld, die Kennzeichnung von Pflichtfeldern über das native required am Eingabefeld und die Verknüpfung von Helper text und Fehlermeldung über aria\-describedby . Nichts davon wird nachgebaut. Das Produktteam verantwortet die Inhalte:

• Da jedes Eingabefeld ein Label haben muss, ist kein zusätzliches aria\-label nötig. Ein am Feld gesetztes aria\-label ersetzt den Namen aus dem sichtbaren Label und darf deshalb nur bei Feldern ohne sichtbares Label verwendet werden.
• Der Platzhalter ist kein Ersatz für das Label und wird nicht zuverlässig vorgelesen. Formathinweise gehören in das Label oder in den Helper text.
• Ein Feld, das dauerhaft nur der Anzeige dient, wird auf Read Only gesetzt: Es bleibt fokussierbar, für Screenreader sichtbar und sein Wert kopierbar. Ein Feld, das im Laufe des Prozesses wieder bearbeitbar werden kann, wird auf Disabled gesetzt: Es ist nicht fokussierbar und für Screenreader unsichtbar und eignet sich deshalb nicht zur Anzeige von Informationen. Siehe States .
• Fehlermeldung: Die Verknüpfung mit dem Eingabefeld stellt die Komponente her. Das Produktteam verantwortet den Text — er muss sagen, wie der Fehler zu beheben ist, und der Fehler darf nicht ausschließlich über Farbe kommuniziert werden.
• Pflichtfeld-Kennzeichnung: Wie Pflichtfelder gekennzeichnet und erklärt werden, regelt Formulare .
• Prefix- und Suffix-Elemente werden von Screenreadern in der Regel nicht zuverlässig vorgelesen. Einheiten oder Symbole, die über Prefix oder Suffix kommuniziert werden, müssen auch im Label oder Helper text verfügbar sein.