MaskedDateField

Das MaskedDateField ist ein Texteingabefeld, das für die strukturierte Eingabe von Daten konzipiert wurde. Es ermöglicht Benutzern, Daten als Zahlen einzugeben und formatiert die Eingabe automatisch basierend auf einer definierten Maske, wenn das Feld den Fokus verliert. Die Maske ist eine Zeichenkette, die das erwartete Datumsformat spezifiziert und sowohl die Eingabe als auch die Anzeige leitet.

Diese Komponente unterstützt flexible Parsing-, Validierungs-, Lokalisierungs- und Wiederherstellungsfunktionen. Sie ist besonders nützlich in Formularen wie Registrierungen, Buchungen und Zeitplänen, in denen konsistente und regionsspezifische Datumsformate erforderlich sind.

Auf der Suche nach einer Zeit-Eingabe?

Das MaskedDateField konzentriert sich ausschließlich auf Datum-Werte. Wenn du eine ähnliche Komponente zum Eingeben und Formatieren von Zeit benötigst, schaue stattdessen in das MaskedTimeField.

Grundlagen

Das MaskedDateField kann mit oder ohne Parameter instanziiert werden. Du kannst einen Startwert, ein Label, einen Platzhalter und einen Ereignis-Listener für Wertänderungen definieren.

Code anzeigen

Java

Maskenregeln

Das MaskedDateField unterstützt mehrere Datumsformate, die weltweit verwendet werden, die sich nach der Reihenfolge von Tag, Monat und Jahr unterscheiden. Zu den häufigsten Mustern gehören:

Tag/Monat/Jahr (verwendet in den meisten europäischen Ländern)
Monat/Tag/Jahr (verwendet in den Vereinigten Staaten)
Jahr/Monat/Tag (verwendet in China, Japan und Korea; auch der ISO-Standard: YYYY-MM-DD)

Innerhalb dieser Formate umfassen lokale Variationen die Wahl des Trennzeichens (z.B. -, / oder .), ob Jahre zwei oder vier Ziffern haben und ob einstellige Monate oder Tage mit führenden Nullen aufgefüllt werden.

Um mit dieser Vielfalt umzugehen, verwendet das MaskedDateField Formatindikatoren, die jeweils mit % beginnen, gefolgt von einem Buchstaben, der einen bestimmten Teil des Datums repräsentiert. Diese Indikatoren definieren, wie Eingaben geparst und wie das Datum angezeigt wird.

Datumsformatindikatoren

Format	Beschreibung
`%Y`	Jahr
`%M`	Monat
`%D`	Tag

Modifikatoren

Modifikatoren ermöglichen eine genauere Kontrolle über die Formatierung der Komponenten des Datums:

Modifikator	Beschreibung
`z`	Nullauffüllen
`s`	Kurze Textdarstellung
`l`	Lange Textdarstellung
`p`	Gepackte Zahl
`d`	Dezimal (Standardformat)

Diese können kombiniert werden, um eine Vielzahl von Datums-Masken zu erstellen.

Lokalisierung des Datumsformats

Das MaskedDateField passt sich regionalen Datumsformaten an, indem das entsprechende Gebietsschema festgelegt wird. Dies stellt sicher, dass Daten in einer Weise angezeigt und geparst werden, die den Erwartungen der Benutzer entspricht.

Region	Format	Beispiel
Vereinigte Staaten	MM/DD/YYYY	`07/04/2023`
Europa	DD/MM/YYYY	`04/07/2023`
ISO-Standard	YYYY-MM-DD	`2023-07-04`

Um die Lokalisierung anzuwenden, verwende die Methode setLocale(). Diese akzeptiert ein java.util.Locale und passt sowohl die Formatierung als auch das Parsing automatisch an:

dateField.setLocale(Locale.FRANCE);

Parsing-Logik

Das MaskedDateField parst Benutzereingaben basierend auf der definierten Datumsmaske. Es akzeptiert sowohl vollständige als auch verkürzte numerische Eingaben mit oder ohne Trennzeichen, was eine flexible Eingabe ermöglicht und gleichzeitig gültige Daten sicherstellt. Das Parsing-Verhalten hängt von der Formatreihenfolge ab, die durch die Maske definiert ist (z.B. %Mz/%Dz/%Yz für Monat/Tag/Jahr). Dieses Format bestimmt, wie numerische Sequenzen interpretiert werden.

Zum Beispiel, wenn heute der 15. September 2012 ist, wird die Eingabe folgendermaßen interpretiert:

Beispielhafte Parsing-Szenarien

Eingabe	YMD (ISO)	MDY (USA)	DMY (EU)
`1`	Eine einzelne Ziffer wird immer als Tag innerhalb des aktuellen Monats interpretiert, sodass dies der 1. September 2012 wäre.	Gleich wie YMD	Gleich wie YMD
`12`	Zwei Ziffern werden immer als Tag innerhalb des aktuellen Monats interpretiert, sodass dies der 12. September 2012 wäre.	Gleich wie YMD	Gleich wie YMD
`112`	Drei Ziffern werden als 1-stellige Monatszahl gefolgt von einer 2-stelligen Tageszahl interpretiert, sodass dies der 12. Januar 2012 wäre.	Gleich wie YMD	Drei Ziffern werden als 1-stellige Tageszahl gefolgt von einer 2-stelligen Monatszahl interpretiert, sodass dies der 1. Dezember 2012 wäre.
`1004`	Vier Ziffern werden als MMDD interpretiert, sodass dies der 4. Oktober 2012 wäre.	Gleich wie YMD	Vier Ziffern werden als DDMM interpretiert, sodass dies der 10. April 2012 wäre.
`020304`	Sechs Ziffern werden als YYMMDD interpretiert, sodass dies der 4. März 2002 wäre.	Sechs Ziffern werden als MMDDYY interpretiert, sodass dies der 3. Februar 2004 wäre.	Sechs Ziffern werden als DDMMYY interpretiert, sodass dies der 2. März 2004 wäre.
`8 Ziffern`	Acht Ziffern werden als YYYYMMDD interpretiert. Beispielsweise ergibt `20040612` den 12. Juni 2004.	Acht Ziffern werden als MMDDYYYY interpretiert. Beispielsweise ergibt `06122004` den 12. Juni 2004.	Acht Ziffern werden als DDMMYYYY interpretiert. Beispielsweise ergibt `06122004` den 6. Dezember 2004.
`12/6`	Zwei Zahlen, die durch ein gültiges Trennzeichen getrennt sind, werden als MM/DD interpretiert, sodass dies der 6. Dezember 2012 wäre. Hinweis: Alle Zeichen außer Buchstaben und Ziffern gelten als gültige Trennzeichen.	Gleich wie YMD	Zwei Zahlen, die durch ein Trennzeichen getrennt sind, werden als DD/MM interpretiert, sodass dies der 12. Juni 2012 wäre.
`3/4/5`	5. April 2012	4. März 2005	3. April 2005

Textuelle Datumsverarbeitung 25.11

Standardmäßig akzeptiert das MaskedDateField nur numerische Eingaben für Daten. Du kannst jedoch die textuelle Datumsverarbeitung aktivieren, um Benutzern zu ermöglichen, Monats- und Tagesnamen in ihre Eingabe einzugeben. Diese Funktion ist besonders nützlich, um eine natürlichere Datumseingabe zu schaffen.

Um die textuelle Verarbeitung zu aktivieren, verwende die Methode setTextualDateParsing():

dateField.setTextualDateParsing(true);

Ersatz von Monatsnamen

Wenn die textuelle Verarbeitung aktiviert ist, kannst du spezielle Modifikatoren in deiner Maske verwenden, um Monatsnamen anstelle von numerischen Werten zu akzeptieren:

%Ms - Akzeptiert kurze Monatsnamen (Jan, Feb, Mär usw.)
%Ml - Akzeptiert lange Monatsnamen (Januar, Februar, März usw.)

Monatsnamen können an jeder Stelle innerhalb der Maske erscheinen, und das Feld akzeptiert weiterhin numerische Eingaben als Fallback.

Beispiele

Maske	Eingabe	Ergebnis
`%Ms/%Dz/%Yz`	`Sep/01/25`	Gültig - Wird als 1. September 2025 geparst
`%Ml/%Dz/%Yz`	`September/01/25`	Gültig - Wird als 1. September 2025 geparst
`%Dz/%Ml/%Yz`	`01/September/25`	Gültig - Wird als 1. September 2025 geparst
`%Mz/%Dz/%Yz`	`09/01/25`	Gültig - Numerischer Fallback funktioniert weiterhin

Info

Alle 12 Monate werden sowohl in kurzer (Jan, Feb, Mär, Apr, Mai, Jun, Jul, Aug, Sep, Okt, Nov, Dez) als auch in langer (Januar, Februar usw.) Form unterstützt.

Dekoration von Tagesnamen

Die Tagesnamen können in die Eingabe aufgenommen werden, um die Lesbarkeit zu verbessern, werden jedoch nur dekorativ behandelt und während des Parsens entfernt. Sie beeinflussen nicht den tatsächlichen Datumswert.

%Ds - Akzeptiert kurze Tagesnamen (Mo, Di, Mi usw.)
%Dl - Akzeptiert lange Tagesnamen (Montag, Dienstag, Mittwoch usw.)

Tagesnamen erfordern eine numerische Tagesangabe

Wenn du Tagesnamen (%Ds oder %Dl) verwendest, muss deine Maske auch %Dz oder %Dd enthalten, um die tatsächliche Tageszahl anzugeben. Ohne eine numerische Tageskomponente wird die Eingabe ungültig sein.

Beispiele

Maske	Eingabe	Ergebnis
`%Ds %Mz/%Dz/%Yz`	`Mo 09/01/25`	Gültig - Tagname ist dekorativ
`%Dl %Mz/%Dz/%Yz`	`Montag 09/01/25`	Gültig - Tagname ist dekorativ
`%Mz/%Dz/%Yz %Ds`	`09/01/25 Di`	Gültig - Tagname am Ende
`%Dl/%Mz/%Yz`	`Montag/09/25`	Ungültig - `%Dz` fehlt
`%Mz/%Dl/%Yz`	`09/Montag/25`	Ungültig - `%Dz` fehlt

Alle 7 Wochentage werden sowohl in kurzer (Mo, Di, Mi, Do, Fr, Sa, So) als auch in langer (Montag, Dienstag usw.) Form unterstützt.

Zusätzliche Parsing-Regeln

Die textuelle Datumsverarbeitung enthält mehrere hilfreiche Funktionen:

Groß-/Kleinschreibung ignoriert: Eingaben wie MONTAG 09/01/25, montag 09/01/25 oder Montag 09/01/25 funktionieren alle gleich.
Locale-bewusst: Monats- und Tagesnamen müssen mit dem konfigurierten Gebietsschema des Feldes übereinstimmen. Verwende beispielsweise mit einem französischen Gebietsschema septembre, nicht September. Englische Namen werden nicht erkannt, es sei denn, das Gebietsschema ist auf Englisch eingestellt.
- Französisches Gebietsschema: septembre/01/25 wird als September erkannt.
- Deutsches Gebietsschema: Montag 09/01/25 wird mit Montag als Tagesnamen erkannt.

Min/Max-Beschränkungen festlegen

Du kannst den zulässigen Datumsbereich in einem MaskedDateField mit den Methoden setMin() und setMax() einschränken:

dateField.setMin(LocalDate.of(2020, 1, 1));
dateField.setMax(LocalDate.of(2030, 12, 31));

Beide Methoden akzeptieren Werte vom Typ java.time.LocalDate. Eingaben außerhalb des definierten Bereichs werden als ungültig betrachtet.

Wiederherstellung des Wertes

Das MaskedDateField enthält eine Wiederherstellungsfunktion, die den Wert des Felds auf einen vordefinierten oder ursprünglichen Zustand zurücksetzt. Dies ist nützlich, um Benutzereingaben zurückzusetzen oder auf ein Standarddatum zurückzusetzen.

dateField.setRestoreValue(LocalDate.of(2025, 1, 1));
dateField.restoreValue();

Möglichkeiten zur Wiederherstellung des Wertes

Programmgesteuert, durch Aufrufen von restoreValue()
Über die Tastatur, indem die Taste ESC gedrückt wird (dies ist die standardmäßige Wiederherstellungstaste, es sei denn, sie wird von einem Ereignis-Listener überschrieben)

Du kannst den Wert, auf den zurückgestellt werden soll, mit setRestoreValue() festlegen, indem du eine LocalDate Instanz übergibst.

Code anzeigen

Java

Validierungs-Muster

Du kannst clientseitige Validierungsregeln mithilfe von regulären Ausdrücken mit der Methode setPattern() anwenden:

dateField.setPattern("^\\d{2}/\\d{2}/\\d{4}$");

Dieses Muster stellt sicher, dass nur Werte, die dem Format MM/DD/YYYY (zwei Ziffern, Schrägstrich, zwei Ziffern, Schrägstrich, vier Ziffern) entsprechen, als gültig angesehen werden.

Format für reguläre Ausdrücke

Das Muster muss der JavaScript RegExp-Syntax entsprechen, die hier dokumentiert ist: hier.

Hinweise zur Eingabeverarbeitung

Das Feld versucht, numerische Datumseingaben basierend auf der aktuellen Maske zu parsen und zu formatieren. Benutzer können jedoch weiterhin manuell Werte eingeben, die nicht dem erwarteten Format entsprechen. Wenn die Eingabe syntaktisch gültig, jedoch semantisch falsch oder unparsbar ist (z.B. 99/99/9999), kann sie die Musterüberprüfungen bestehen, aber gegen die logische Validierung fehlschlagen. Du solltest den Eingabewert immer in deiner Anwendungslogik validieren, selbst wenn ein reguläres Ausdrucksmuster festgelegt ist, um sicherzustellen, dass das Datum sowohl korrekt formatiert als auch sinnvoll ist.

Datumsauswahl

Das MaskedDateField enthält einen integrierten Kalenderauswähler, der es Benutzern ermöglicht, ein Datum visuell auszuwählen, anstatt es einzugeben. Dies verbessert die Benutzerfreundlichkeit für weniger technikaffine Benutzer oder wenn eine präzise Eingabe erforderlich ist.

Code anzeigen

Java

Zugriff auf den Auswähler

Du kannst auf den Datumswähler mit getPicker() zugreifen:

DatePicker picker = dateField.getPicker();

Kalender-Symbol anzeigen/verbergen

Verwende setIconVisible(), um das Kalendersymbol neben dem Feld anzuzeigen oder zu verstecken:

picker.setIconVisible(true); // zeigt das Symbol an

Automatisches Öffnungsverhalten

Du kannst den Picker so konfigurieren, dass er automatisch geöffnet wird, wenn der Benutzer mit dem Feld interagiert (z.B. klickt, Enter drückt oder Pfeiltasten verwendet):

picker.setAutoOpen(true);

Auswahl über den Wähler erzwingen

Um sicherzustellen, dass Benutzer nur ein Datum über den Kalenderauswähler auswählen können (und nicht manuell eingeben), kombiniere die folgenden beiden Einstellungen:

dateField.getPicker().setAutoOpen(true); // Öffnet den Wähler bei Benutzerinteraktion
dateField.setAllowCustomValue(false);    // Deaktiviert die manuelle Texteingabe

Diese Konfiguration garantiert, dass alle Datumseingaben über die Benutzeroberfläche des Wählers erfolgen, was nützlich ist, wenn du strikte Formatkontrolle und das Elimieren von Parsing-Problemen durch manuelle Eingaben wünschst.

Kalender manuell öffnen

Um den Kalender programmgesteuert zu öffnen:

picker.open();

Oder verwende den Alias:

picker.show(); // dasselbe wie open()

Wochen im Kalender anzeigen

Der Picker kann optional Wochenzahlen in der Kalenderansicht anzeigen:

picker.setShowWeeks(true);