Email Field

Das Email Field ist ein Eingabefeld, mit dem eine E-Mail-Adresse erfasst wird.

Overview

Intro

Das Email Field ermöglicht dem Nutzer die Eingabe einer E-Mail-Adresse. Üblicherweise wird es innerhalb von Formularen verwendet, z.B. bei der Registrierung, im Kontaktformular oder in den Profildaten.

Das Email Field ist eine Erweiterung des Text Field und akzeptiert ausschließlich E-Mail-Adressen als Eingabe. Standardmäßig prüft ein vordefinierter regulärer Ausdruck das Format der eingegebenen Adresse. Entspricht die Eingabe nicht diesem Format, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes.

Verwendung

👍 Do

👎 Don't

... wenn genau eine E-Mail-Adresse erfasst werden soll (z.B. in einem Registrierungs-, Kontakt- oder Profilformular).

... wenn ein Freitext oder eine alphanumerische Eingabe erfasst werden soll, verwende dazu das Text Field ... wenn ein längerer, mehrzeiliger Text erfasst werden soll, verwende dazu die Text Area ... wenn ein Passwort erfasst werden soll, verwende dazu das Password Field ... wenn ein numerischer Wert schrittweise angepasst werden soll, verwende dazu das Number Field ... wenn eine bereits erfasste E-Mail-Adresse nur angezeigt und nicht bearbeitet werden soll, verwende dazu Name-Wert-Facetten

Guidelines

Aufbau

Das Email 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 genau eine E-Mail-Adresse auf, die der Nutzer eintippt.
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um Informationen zu kommunizieren, die der Nutzer für die Eingabe benötigt, z.B. Formatanforderungen oder den Zweck des Feldes. Eine Style-Variante erlaubt die Darstellung oberhalb des Feldes.
• Placeholder (optional) — wird angezeigt, solange das Feld leer ist, und gibt einen kurzen Eingabehinweis, z.B. das erwartete Format. Nur zu verwenden, wenn kein Helper text möglich ist. Ein Placeholder ersetzt kein sichtbares Label, da er für einen bereits eingegebenen Wert gehalten werden kann.
• 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) — werden am Anfang bzw. am Ende des Feldes dargestellt. Für das Prefix ist ein Briefumschlag-Icon die übliche Wahl. Zu den Grenzen bei Screenreadern siehe Barrierefreiheit .
• 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. Besonders nützlich 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.

Verhalten

Der Nutzer tippt die E-Mail-Adresse direkt in das Feld ein. Die Zeicheneingabe erfolgt wie bei einem Text Field: Das Email Field formatiert die Eingabe nicht und maskiert sie nicht, geprüft wird der eingegebene Wert. Ein Feld nimmt genau eine Adresse auf.

Das Feld verwendet den Eingabetyp email . Mobile Tastaturen blenden dadurch die für E-Mail-Adressen typischen Zeichen ein, und die automatische Großschreibung des ersten Zeichens ist ausgeschaltet.

Ist der Clear button aktiviert, löscht ein Klick darauf den aktuellen Wert. Bei fokussiertem Feld löscht ihn auch die Escapetaste ( Esc ) — vorausgesetzt, der Clear button ist sichtbar, das Feld enthält einen Wert und ist nicht auf Read Only gesetzt.

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. Ist das Feld bereits ungültig, wird bei jeder weiteren Eingabe erneut geprüft, sodass die Meldung beim Korrigieren sofort verschwindet.

Die Formatprüfung ist immer aktiv, weil ab Werk ein Muster gesetzt ist. Sie prüft ausschließlich die Schreibweise der Adresse und sagt nicht aus, ob es die Adresse gibt.

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.
Pattern	Ein regulärer Ausdruck prüft den vollständigen Wert. Standardmäßig ist ein vordefiniertes Muster gesetzt, das Vaadin als Muster nach dem Standard RFC 5322 dokumentiert. Das Muster kann überschrieben werden, um weitere Einschränkungen zu ergänzen, z.B. nur eine bestimmte Domain zuzulassen; die Standardprüfung des Formats entfällt damit.
Min / Max length (geerbt, nicht vorgesehen)	Die Mindestlänge löst einen Validierungsfehler aus, wenn ein kürzerer Wert eingegeben wird; die Maximallänge begrenzt den eingegebenen Text. Für E-Mail-Adressen ist das selten nötig.
Allowed characters (geerbt, nicht vorgesehen)	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.

Für das Email Field sind Required und Pattern vorgesehen. Min / Max length stammen aus dem Text Field, Allowed characters aus der gemeinsamen Basis der Eingabefelder; beide sind für das Email Field nicht vorgesehen und nicht zugesichert. Wer sie dennoch einsetzt, prüft ihr Verhalten im eigenen Framework selbst.

Das voreingestellte Muster ist enger als der Standard: Es prüft ausschließlich ASCII-Zeichen. Im lokalen Teil sind nur Buchstaben, Ziffern, Unterstrich, Bindestrich und Plus zulässig, Punkte nur als Trenner; die Domain braucht eine Endung von mindestens zwei Zeichen. Adressen mit Umlaut-Domains oder weiteren nach dem Standard zulässigen Sonderzeichen werden abgewiesen. Werden solche Adressen erwartet, ist das Muster zu überschreiben.

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

States

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

• Default — leer und bearbeitbar.
• Filled — das Feld enthält eine E-Mail-Adresse.
• 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 Email Field im State Enabled kann die Eingabe wie gewohnt erfolgen.

Der Clear button ist selbst nicht über die Tastatur fokussierbar. Ist er aktiviert, wird die Löschaktion bei fokussiertem Feld über die Escapetaste ( Esc ) ausgelöst.

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. "Gültige E-Mail-Adresse 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. Ein Briefumschlag-Icon im Prefix ersetzt daher weder das Label noch einen Hinweis auf das erwartete Format; diese Information muss über Label, Helper text oder ARIA-Attribute verfügbar sein.