Date Picker

Der Date Picker ist ein Eingabefeld, mit dem ein Datum ausgewählt werden kann.

Overview

Intro

Der Date Picker ermöglicht dem Nutzer ein Datum auszuwählen. Üblicherweise wird er innerhalb von Formularen verwendet.

broken_image

Figma

Beispiel Date Picker

Verwendung

👍 Do	👎 Don't
... wenn ein Datum erfasst werden soll (z.B. in einem Formular)	... wenn ein Datumsbereich erfasst werden soll (siehe hierzu Datumsbereich durch Bereichsauswahl) ... wenn ein Datum und eine Uhrzeit erfasst werden soll (siehe hierzu Date Time Picker) ... wenn eine Uhrzeit erfasst werden soll (siehe hierzu Time Picker)

Guidelines

Aufbau

Der Date Picker setzt sich aus folgenden Bestandteilen zusammen. Label, Eingabefeld, Toggle button und Date Picker Overlay 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 das Datum auf, das der Nutzer eintippt, und zeigt das im Overlay gewählte Datum an.
• Toggle button — das Kalender-Icon am Ende des Feldes öffnet und schließt das Overlay. Er ist selbst nicht tastaturfokussierbar und für Screenreader ausgeblendet; im State Read Only wird er ausgeblendet.
• Date Picker Overlay — zeigt einen Kalender, in dem der Nutzer durch Monate und Jahre scrollt und einen Tag auswählt. Unterhalb des Kalenders stehen die Schaltflächen "Heute" und "Abbrechen".
• Helper text (optional) — erscheint unterhalb des Feldes. Geeignet, um das erwartete Datumsformat oder den zulässigen Zeitraum zu erläutern. 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 Format der Datums-Eingabe. 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 (optional) — Element am Anfang des Feldes. Ein Suffix gibt es nicht, denn am Ende des Feldes stehen bereits Clear button und Toggle button. Screenreader lesen das Prefix 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 den Wert. Ist das Overlay geöffnet, schließt sie zunächst das Overlay.
• 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 ist der Date Picker das Element <vaadin-date-picker> aus dem Paket @vaadin/date-picker. Das Paket ist in @mate/bundles enthalten.

In Vue liegt er im Paket @mate-vue/date-picker und heißt MateDatePicker.

In Flow stammt die Klasse DatePicker aus dem Maven-Artefakt vaadin-date-picker-flow der groupId com.vaadin und dem Paket com.vaadin.flow.component.datepicker.

Verhalten

Beim Klick auf das Date Picker Icon oder in den Date Picker klappt das Date Picker Overlay auf. Hier kann der Nutzer durch die verschiedenen Monate und Jahre scrollen. Bewegt der Nutzer die Maus über einen Tag wird dieser farblich hervorgehoben. Beim Klick auf einen Tag wird das Datum ausgewählt. Des Weiteren ist es auch möglich das Datum per Tastatur einzutippen. Das aktuelle Datum ist zudem auch farblich und durch einen Unterstrich hervorgehoben.

broken_image Figma	Geöffneter Date Picker
broken_image Figma	Beim Hovern über einem Tag
broken_image Figma	Mit ausgewähltem Tag

Parser Verhalten

Der Parser, der beim Date Picker eingebunden werden kann, verhält sich wie nachfolgend dargestellt:

Fall 1

Falls eine oder zwei Ziffern eingegeben werden, wird das Datum mit aktuellem Monat und Jahr komplettiert.

7 → 07.11.2019

15 → 15.11.2019

Fall 2

Falls drei Ziffern eingegeben werden, werden die ersten Beiden als Tag und die dritte als Monat interpretiert, komplettiert mit dem aktuellen Jahr.

111 → 11.01.2019

237 → 23.07.2019

Fall 3

Falls vier Ziffern eingegeben werden, wird das Datum mit aktuellem Jahr komplettiert.

2403 → 24.03.2019

Fall 4

Falls fünf Ziffern eingegeben werden, werden die Ziffern eins und zwei als Tag, die Ziffern drei und vier als Monat und Ziffer fünf als Teilangabe eines Jahres interpretiert. In diesem Fall wird das Jahr zum aktuellen Jahrhundert mit Dekade 0 komplettiert.

26117 → 26.11.2007: Die Dekade wird mit einer führenden 0 ergänzt, analog dem Verhalten bei Monaten.

Fall 5

Falls sechs Ziffern eingegeben werden, werden die letzten beiden Ziffern als Jahresangabe im aktuellen Jahrhundert interpretiert.

260318 → 26.03.2018

Fall 6

Beim Verlassen des Feldes werden fehlende Punkte automatisch ergänzt.

01012019 → 01.01.2019

Fall 7

Beim Verlassen des Feldes, werden Tag und Monat immer mit zwei Stellen angegeben. Fall notwendig wird eine führende Null ergänzt.

6.3.18 → 06.03.2018

Fall 8

Falls das erste Zeichen ein Operator ist ( +(plus), -(minus) ) wird der nachfolgende Zeitraum zum aktuellen Tagesdatum hinzugerechnet. Ein Zeitraum besteht aus einer (positiven) Zahl und einem optionalen Zeitraumindikator ( t (Tage)(default), m(Monate), j(Jahre) )

Angenommen, das aktuelle Datum ist: 15.05.2020

+4 → 19.05.2020

+4t → 19.05.2020

+3m → 15.08.2020

+5j → 15.05.2025

-4 → 11.05.2020

-4t → 11.05.2020

-3m → 15.02.2020

-5j → 15.05.2015

Validierung

Die Validierung erfolgt, wenn der Nutzer eine Wertänderung auslöst, z.B. durch Auswahl eines Tages im Overlay oder durch Eingabe und Drücken von Enter . Spätestens beim Verlassen des Feldes wird die Eingabe übernommen und geprüft. Ist der Wert ungültig, wird das Feld rot hervorgehoben und eine Fehlermeldung erscheint unterhalb des Eingabefeldes.

Eine Eingabe, die sich nicht in ein Datum umsetzen lässt, macht das Feld ungültig; sie bleibt im Feld stehen, damit sie korrigiert werden kann. Welche unvollständigen Eingaben zu einem Datum ergänzt werden, steht unter Parser Verhalten .

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	Legen das früheste und das späteste wählbare Datum fest. Alle Tage außerhalb dieses Bereichs sind im Overlay Disabled; ein Datum außerhalb des Bereichs macht das Feld ungültig. Der erlaubte Bereich sollte über den Helper text kommuniziert werden.
Nicht wählbare Einzeltage	Über eine Prüffunktion lässt sich für jedes Datum einzeln festlegen, ob es wählbar ist. Nicht wählbare Tage sind im Overlay Disabled und machen das Feld ungültig, auch wenn sie eingetippt werden.
Nicht parsbare Eingabe	Jede Eingabe, die nicht in ein gültiges Datum umgesetzt werden kann, macht das Feld ungültig. Dieser Constraint ist nicht konfigurierbar und immer aktiv.

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

States

broken_image Figma	Enabled Ein Date Picker im State Enabled kann vom Nutzer fokussiert werden und die Eingabe des Datums kann per Tastatur im Feld, oder über das Overlay erfolgen. Letzteres öffnet sich durch einen Klick in das Feld oder auf das Icon.
broken_image Figma	Error Date Picker können validiert werden. Je nach Ergebnis der Validierung wird der Date Picker hervorgehoben. Im State Error erscheint die Fehlermeldung unterhalb vom Date Picker 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.
broken_image Figma	Hilfe-Text Wenn nötig, kann unterhalb des Date Pickers ein Hilfetext angezeigt werden. Dieser gibt dem Nutzer weitere Informationen über die benötigte Eingabe.

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

Barrierefreiheit

Tastaturbedienung

Über Tabulatortaste ("Tab") oder Hochstell- und Tabulatortaste ("Shift" + "Tab") ist der Date Picker fokussierbar. Nach dem Öffnen des Overlays mit der Leertaste, können einzelne Tage mit den Pfeiltasten angesteuert werden. Durch das Drücken der Pfeiltaste nach oben und der Pfeiltaste nach unten kann zwischen den Monaten und damit auch zwischen den Jahren gewechselt werden. Ist ein Tag im Fokus, nachdem er mit den Pfeiltasten angesteuert wurde, kann dieser mittels Eingabetaste ("Enter") und auch per Leerzeichentaste ("Space") ausgewählt werden. Der Date Picker schließt bei gleichzeitiger Auswahl des Tages und durch das Drücken der Eingabetaste ("Enter").

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, die Verknüpfung von Helper text und Fehlermeldung über aria\-describedby und die Ansage des Overlays über aria\-haspopup und aria\-expanded . 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. "Datum im Format TT.MM.JJJJ 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 .