🔴Number Field

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

Overview

Intro

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.

Das Number Field akzeptiert ausschließlich ganzzahlige Werte.

Beispiele:

Anzahl Kopien - Number Field

Suchkriterien - Number Field

Mindestanzahl x - Number Field

Anzahl Kinder - Dropdown

Geburtsjahr - Dropdown

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 User eingegeben werden soll - die übiche Auswahl der Eingabe i.d.R. mehr als 10 Ergebnisse hat - ein Dezimalwert erfasst werden soll. - Zahlen größer 99 in Betracht kommen

Guidelines

Aufbau

Das Number Field hat immer ein Label , das die erwartete Eingabe kennzeichnet, sowie ein Eingabefeld , in das der Nutzer die Zahl eintippen kann. Die Step buttons (+ und −) sind standardmäßig sichtbar. Optional können folgende Elemente ergänzt werden:

• Label — kennzeichnet das Feld. Für die Barrierefreiheit erforderlich. Unterstützt Plaintext-Inhalt; die Länge ist durch die Breite des Feldes begrenzt.
• Step buttons — ermöglichen dem Nutzer, den Wert schrittweise zu erhöhen oder zu verringern. Können deaktiviert werden, wenn ausschließlich die Tastatureingabe vorgesehen ist.
• 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.
• 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.
• Required indicator (bei Bedarf) — Pflichtfelder werden durch einen Indikator neben dem Label gekennzeichnet. Empfohlen wird ein Hinweistext am Anfang des Formulars, der die Bedeutung des Indikators erklärt.Verhalten

Wenn das Number Field sein Minimum erreicht hat (0 oder 1, je nach Fall), sollte das Minus im inaktiven Zustand sein.

Wenn das Number Field sein Maximum erreicht hat (je nach Fall), sollte das Plus im inaktiven Zustand sein.

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. Nicht-numerische Zeichen werden abgewiesen.

Step buttons

Die Step buttons erhöhen oder verringern den aktuellen Wert um den definierten Step-Wert. Der Standard-Step-Wert ist 1. 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 deaktiviert, wenn der Max-Wert erreicht ist; der Step button für "verringern" wird deaktiviert, wenn der Min-Wert erreicht ist.

Validierung

Die Validierung erfolgt üblicherweise, wenn der Nutzer eine Wertänderung auslöst, z.B. durch Eingabe und Drücken von Enter . Ist der Wert ungültig, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes.

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 — das Number Field benötigt keine eigenen State-Darstellungen.

• Default — leer und bearbeitbar; Step buttons sichtbar.
• Filled — das Feld enthält einen Wert.
• Invalid — 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 Aktiv , Disabled , Read Only , Hover und Fokus 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 aktiven fokussierten Number Field 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.

Spezifische Hinweise

• Da jedes Eingabefeld ein Label haben muss, ist kein zusätzliches aria-label nötig.
• Platzhalter (Placeholder) im Eingabefeld können optional zugänglich gemacht werden, indem sie im aria-label Attribut angegeben werden.
• Gesperrte Eingabefelder sollten standardmäßig nicht über die Tastatur fokussierbar sein. Erst wenn der Nutzer entsprechende Einstellungen vornimmt, sollten auch die gesperrten Eingabefelder in den Fokussierungs-Kreislauf aufgenommen werden.
• Fehleridentifikation & Korrekturhinweis: Schlägt die Validierung fehl, muss der Fehler programmatisch mit dem Feld verknüpft sein (nicht ausschließlich über Farbe kommuniziert) und die Meldung muss dem Nutzer mitteilen, wie er den Fehler korrigieren kann (z.B. "Bitte einen Wert zwischen 1 und 10 eingeben", nicht nur "Fehler").
• Pflichtfeld-Kennzeichnung: Am Anfang des Formulars muss ein Hinweistext stehen, der die Bedeutung des Required indicator erklärt.
• 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).

Develop Vue

Die Implementierung der Webcomponenten in Vue.js kann in folgendem Showcase innerhalb des AKDB Netzwerks betrachtet werden: https://mate-ds-vue-components-showcase-25.core-platform.kubt.akdb.net/?path=/story/komponenten-text-field--number-default

Develop Flow

Der Showcase ist innerhalb des AKDB Netzwerks zu finden unter: https://mate-ds-flow-components-showcase-25.core-platform.kubt.akdb.net/?src=component%252Fnumber-field

Code Examples

Install

Maven

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-text-field-flow</artifactId>
</dependency>

Import

import com.vaadin.flow.component.textfield.NumberField;

Variants

Default

NumberField numberField = new NumberField();
numberField.setLabel("Anzahl");
numberField.setValue(1.0);
numberField.setHelperText("Geben Sie einen Zahlenwert ein");
numberField.setStepButtonsVisible(true);

Required

NumberField numberField = new NumberField();
numberField.setLabel("Pflichtfeld");
numberField.setValue(1.0);
numberField.setRequired(true);
numberField.setStepButtonsVisible(true);

Disabled

NumberField numberField = new NumberField();
numberField.setLabel("Inaktiv");
numberField.setValue(1.0);
numberField.setEnabled(false);
numberField.setStepButtonsVisible(true);

Read Only

NumberField numberField = new NumberField();
numberField.setLabel("Nur lesen");
numberField.setValue(1.0);
numberField.setReadOnly(true);

Invalid

NumberField numberField = new NumberField();
numberField.setLabel("Ungültig");
numberField.setValue(1.0);
numberField.setManualValidation(true);
numberField.setInvalid(true);
numberField.setErrorMessage("Bitte einen gültigen Zahlenwert eingeben.");