Text Area

Die Text Area ist ein mehrzeiliges Eingabefeld, mit dem längere Freitexte erfasst werden.

Overview

Intro

broken_image

Figma

Text Area

Die Text Area ermöglicht dem Nutzer die Eingabe von Text über mehrere Zeilen. Üblicherweise wird sie in Formularen für Beschreibungen, Kommentare, Bemerkungen und andere längere Freitexte verwendet. Die Eingabe ist immer unformatiert, d. h. die reine Zeichenfolge wird erfasst. Zeilenumbrüche, die der Nutzer setzt, bleiben Teil des Wertes.

Wie jedes Eingabefeld hat auch die Text Area einen klaren Zweck, der als Label angezeigt wird (z.B. Bemerkung, Begründung, Sachverhalt).

Verwendung

👍 Do

👎 Don't

... wenn längere Freitexte erfasst werden, die über eine Zeile hinausgehen (z.B. Bemerkungen, Beschreibungen, Begründungen). ... wenn die Länge der Eingabe im Voraus nicht feststeht. ... wenn der Nutzer seine Eingabe in Absätze gliedern soll.

... wenn kurze, einzeilige Daten erfasst werden, verwende dazu das Text Field . ... wenn eine E-Mail-Adresse erfasst werden soll, verwende dazu das Email Field . ... 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 bereits erfasste Daten nur angezeigt werden sollen, verwende dazu Name-Wert-Facetten . ... wenn der Text formatiert werden soll (z.B. Fettschrift, Aufzählungen) – die Text Area erfasst ausschließlich unformatierten Text.

Guidelines

Aufbau

Die Text Area 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 Text auf, den der Nutzer eintippt. Es ist mehrzeilig und wächst mit dem Inhalt; die Regeln dafür stehen unter Höhe.
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um Formatanforderungen, den Zweck des Feldes oder die zulässige Zeichenzahl 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. 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 .

Für Breite, Anordnung und Spaltenbelegung gilt die Regel des Form Layout : Eine Text Area nimmt immer die volle Breite der Formularspalte ein.

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.

Höhe

Verhalten der Komponente

Ohne feste Höhe wächst die Text Area mit ihrem Inhalt. Die Ausgangs- und Mindesthöhe wird über eine Mindestzahl an Zeilen festgelegt, die Maximalhöhe über eine Höchstzahl an Zeilen.

• Die Mindestzahl an Zeilen hat den Vorgabewert 2. Die Text Area ist damit zunächst 2 Textzeilen hoch und wird nie kleiner. Werte kleiner als 1 wirken wie 1.
• Die Höchstzahl an Zeilen ist standardmäßig nicht gesetzt. Ohne diesen Wert wächst das Feld unbegrenzt mit dem Inhalt.
• Ist eine Höchstzahl gesetzt, begrenzt sie die Höhe des Feldes. Sobald der Inhalt darüber hinausgeht, scrollt er innerhalb des Feldes.
• Alternativ lässt sich die automatische Anpassung über feste Min- und Max-Pixelwerte begrenzen.
• Der Nutzer kann die Höhe nicht selbst mit der Maus verändern.

Vorgabe des Mate Design Systems

Die Ausgangshöhe einer Text Area beträgt 4 Zeilen, die Maximalhöhe 8 Zeilen. Bis zur Maximalhöhe wächst das Feld mit dem Inhalt, darüber scrollt der Inhalt im Feld. Diese Werte gelten für jede Text Area. Sie weichen von den Vorgabewerten der Komponente ab und werden deshalb an jedem Feld gesetzt.

Info für Dev

Die Mate-Vorgabe ist nicht als Vorgabewert der Komponente hinterlegt. An jeder Text Area sind die Attribute min-rows="4" und max-rows="8" zu setzen, in Flow setMinRows(4) und setMaxRows(8).

Verhalten

Bei Klick in die Text Area wird der Cursor in das Feld gesetzt und der Nutzer kann die Eingabe beginnen. Die Eingabetaste ( Enter ) fügt einen Zeilenumbruch ein: Sie schließt die Eingabe nicht ab und löst keine Validierung aus. Der Wechsel in das nächste Feld erfolgt deshalb immer über die Tabulatortaste.

Mit jeder Änderung passt das Feld seine Höhe an den Inhalt an, bis die festgelegte Maximalhöhe von 8 Zeilen erreicht ist. Danach bleibt die Höhe konstant und der Inhalt scrollt im Feld.

Ist ein Clear button vorhanden, löscht die Escapetaste ( Esc ) bei fokussiertem Feld den gesamten Wert.

Validierung

Die Validierung erfolgt, wenn der Nutzer eine Wertänderung auslöst. Anders als bei den einzeiligen Eingabefeldern schließt die Eingabetaste den Wert nicht ab, sondern setzt einen Zeilenumbruch; geprüft wird deshalb spätestens beim Verlassen des Feldes. Ist der Wert ungültig, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Feldes. Nach einer fehlgeschlagenen Validierung wird bei jeder weiteren Eingabe erneut geprüft, sodass die Fehlermeldung verschwindet, sobald der Wert gültig ist.

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. Der erlaubte Umfang sollte über den Helper text kommuniziert werden.
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. Nicht erlaubte Zeichen 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.

Zeichenzähler

Ist die Zeichenzahl begrenzt, werden die aktuelle Anzahl und die zulässige Höchstzahl angezeigt, zum Beispiel "128/500". Einen eigenen Zeichenzähler bringt die Komponente nicht mit: Die Anwendung schreibt den Stand bei jeder Wertänderung in den Helper text.

States

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

• Default — leer und bearbeitbar, in der Ausgangshöhe von 4 Zeilen.
• Filled — das Feld enthält einen Wert und ist in seiner Höhe an dessen Umfang angepasst.
• Error — das Feld ist rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Feldes. 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 .

Für die reine Anzeige bereits erfasster Daten sind Name-Wert-Facetten vorgesehen.

Barrierefreiheit

Tastaturbedienung

Über die Tabulatortaste ( Tab ) oder Hochstell- und Tabulatortaste ( Shift + Tab ) lässt sich zwischen den einzelnen Eingabefeldern springen. In einer fokussierten Text Area im State Enabled kann die Eingabe wie gewohnt erfolgen. Die Eingabetaste ( Enter ) fügt einen Zeilenumbruch ein und verlässt das Feld nicht; das Feld wird ausschließlich über die Tabulatortaste verlassen.

Ist die Höhe durch die Maximalhöhe begrenzt, bleibt der gesamte Inhalt über die Tastatur erreichbar.

Der Clear button ist nicht über die Tastatur 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.
• Ist ein sichtbares Label ausnahmsweise nicht möglich, wird entweder ein externes Element als Label mit dem Feld verknüpft oder ein unsichtbares Label für assistive Technologien gesetzt. Sichtbare Labels sind ausdrücklich empfohlen.
• 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 am Feld gesetztes aria\-label ersetzt den Namen aus dem sichtbaren Label und darf deshalb nur bei Feldern ohne sichtbares Label verwendet werden.
• 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. "Mindestens 5 Zeichen 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. Informationen, die über Prefix oder Suffix kommuniziert werden, müssen auch im Label oder Helper text verfügbar sein.
• Der Helper text ist automatisch mit dem Eingabefeld verknüpft und wird beim Fokussieren mit ausgegeben. Ein laufend aktualisierter Zeichenzähler wird dabei nicht bei jeder Änderung angesagt.