Number Field

Die Number Field Komponente wird verwendet, um numerische und veränderbare Eingaben des Nutzers abzubilden.

Overview

Intro

broken_image

Figma

Number Field

Das Number Field ermöglicht dem Nutzer die Eingabe einer ganzen Zahl. Step buttons erlauben dem Nutzer, kleine Anpassungen schnell vorzunehmen. Üblicherweise wird es in Formularen verwendet, in denen ein präziser, diskreter numerischer Wert erfasst werden soll.

Im Mate Design System wird das Number Field ausschließlich für ganzzahlige Werte verwendet.

Beispiele:

Anzahl Kopien - Number Field

Suchkriterien - Number Field

Mindestanzahl x - Number Field

Anzahl Kinder - Dropdown

Geburtsjahr - Textfield

Verwendung

👍 Do

👎 Don't

Verwenden wenn: - eine nicht feststehende, numerische Eingabe bearbeitet wird. - die übliche Auswahl der Eingabe i.d.R. nicht mehr als 10 Ergebnisse hat.

Nicht verwenden wenn: - eine feststehende Zahl vom Nutzer eingegeben werden soll. - die übliche Auswahl der Eingabe i.d.R. mehr als 10 Ergebnisse hat. - ein Dezimalwert erfasst werden soll. - Zahlen größer 99 in Betracht kommen. - bereits erfasste Daten nur angezeigt werden sollen, verwende dazu Name-Wert-Facetten . - ein Freitext oder eine alphanumerische Eingabe erfasst werden soll, verwende dazu das Text Field . - ein längerer, mehrzeiliger Text erfasst werden soll, verwende dazu die Text Area . - eine E-Mail-Adresse erfasst werden soll, verwende dazu das Email Field . - ein Passwort erfasst werden soll, verwende dazu das Password Field .

Guidelines

Aufbau

Das Number Field setzt sich aus folgenden Bestandteilen zusammen. Label, Eingabefeld und Step buttons 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 die Zahl auf, die der Nutzer eintippt.
• Step buttons — die Minus-Schaltfläche am linken und die Plus-Schaltfläche am rechten Rand des Feldes ermöglichen dem Nutzer, den Wert schrittweise zu verringern oder zu erhöhen. Im Mate Design System werden sie immer angezeigt. Sie sind selbst nicht tastaturfokussierbar und für Screenreader ausgeblendet; der gleichwertige Weg über die Tastatur sind die Pfeiltasten.
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um den erlaubten Wertebereich zu kommunizieren (z.B. "1 bis 10 Personen"). 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, und ersetzt kein sichtbares Label.
• 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 und Symbole. Screenreader lesen sie in der Regel nicht zuverlässig vor; die Information muss zusätzlich über Label oder Helper text 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 ( Esc ) den Wert.
• 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.

Zwei Voreinstellungen des Elements entsprechen nicht der Mate-Regel und werden an jedem Number Field gesetzt: step-buttons-visible blendet die Step buttons ein, ohne das Attribut sind sie ausgeblendet. Und step="1" erzwingt ganzzahlige Werte, denn ohne gesetzten Step nimmt vaadin-number-field auch Dezimalwerte an.

Verhalten

Der Nutzer kann den Wert auf zwei Arten eingeben: direkt durch Tippen im Eingabefeld, oder über die Step buttons und die Pfeiltasten der Tastatur. Der Browser verhindert die Eingabe der meisten nicht-numerischen Zeichen; verbleibende nicht auswertbare Eingaben macht der Constraint Bad input ungültig.

Step buttons

Die Step buttons erhöhen oder verringern den aktuellen Wert um den definierten Step-Wert. Im Mate Design System ist der Step-Wert 1, sodass sich der Wert in ganzen Schritten ändert. Der Wert kann auch über die Pfeiltaste nach oben und die Pfeiltaste nach unten angepasst werden, wenn das Feld den Fokus hat.

Der Step-Wert definiert auch, welche numerischen Intervalle als gültig akzeptiert werden — ein Wert, der nicht einem Vielfachen des Steps entspricht, macht das Feld ungültig.

Min- und Max-Werte begrenzen den erreichbaren Bereich: Der Step button für "erhöhen" wird auf Disabled gesetzt, wenn der Max-Wert erreicht ist; der Step button für "verringern" wird auf Disabled gesetzt, wenn der Min-Wert erreicht ist.

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	Definiert den erlaubten Wertebereich. Ein Wert unterhalb des Minimums oder oberhalb des Maximums macht das Feld ungültig. Helper text sollte den erlaubten Bereich kommunizieren.
Step	Ein Wert, der kein Vielfaches des definierten Steps ist, macht das Feld ungültig.
Bad input	Jede Eingabe, die nicht in einen gültigen numerischen Wert geparst werden kann, macht das Feld ungültig und setzt den Wert zurück. Dieser Constraint ist nicht konfigurierbar und standardmäßig aktiv.
Allowed characters	Ein regulärer Ausdruck für einzelne Zeichen kann einschränken, welche Zeichen eingegeben werden dürfen. Programmatisch gesetzte Werte unterliegen dieser Einschränkung nicht.

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

States

Das Number Field unterstützt die Standard-Eingabefeld-States. Visuell folgen sie der gleichen Darstellung wie beim Rest der Mate DS Eingabefeld-Familie — das Number Field benötigt keine eigenen State-Darstellungen.

• Default — leer und bearbeitbar.
• Filled — das Feld enthält einen Wert.
• Error — das Feld ist rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes. Wird ausgelöst, wenn ein Validierungs-Constraint verletzt wird.

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

Barrierefreiheit

Tastaturbedienung

Über die Tabulatortaste ( Tab ) oder Hochstell- und Tabulatortaste ( Shift + Tab ) lässt sich zwischen den einzelnen Eingabefeldern springen. In einem fokussierten Number Field im State Enabled kann die Eingabe wie gewohnt erfolgen. Über die Pfeiltaste nach oben ( ↑ ) und die Pfeiltaste nach unten ( ↓ ) kann der Wert schrittweise angepasst werden, ohne die Step buttons zu verwenden.

Der Clear button ist nicht über die Tastatur fokussierbar. Ist er aktiviert, löscht die Escapetaste ( Esc ) bei fokussiertem Feld 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 (z.B. "Wert zwischen 1 und 10 eingeben" , nicht nur "Fehler" ), 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 (z.B. "Anzahl Personen (1–9)" statt nur ein "Stk."-Suffix).