MaskedDateField

Das MaskedDateField ist ein Texteingabefeld, das für die strukturierte Dateneingabe konzipiert ist. 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 angibt und sowohl die Eingabe als auch die Anzeige steuert.

Diese Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wiederherstellung von Werten. Sie ist besonders nützlich in Formularen wie Registrierungen, Buchungen und Zeitplänen, wo konsistente und regionsspezifische Datumsformate erforderlich sind.

Suchen Sie nach einer Zeit-Eingabe?

Das MaskedDateField konzentriert sich ausschließlich auf Datum-Werte. Wenn Sie eine ähnliche Komponente für die Eingabe und Formatierung von Zeit benötigen, sehen Sie sich stattdessen das MaskedTimeField an.

Grundlagen

Das MaskedDateField kann mit oder ohne Parameter instanziiert werden. Sie können einen Anfangswert, 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 und sich in der Reihenfolge von Tag, Monat und Jahr unterscheiden. Häufige Muster sind:

Tag/Monat/Jahr (wird in den meisten Teilen Europas verwendet)
Monat/Tag/Jahr (wird in den Vereinigten Staaten verwendet)
Jahr/Monat/Tag (wird in China, Japan und Korea verwendet; auch der ISO-Standard: JJJJ-MM-TT)

Innerhalb dieser Formate gibt es lokale Variationen, einschließlich der Wahl des Trennzeichens (z. B. -, / oder .), ob Jahre zwei oder vier Ziffern haben und ob einstellige Monate oder Tage mit führenden Nullen ausgefü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 darstellt. Diese Indikatoren definieren, wie Eingaben geparst und wie das Datum angezeigt wird.

Datumsformat-Indikatoren

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

Modifikatoren

Modifikatoren ermöglichen eine genauere Kontrolle darüber, wie Komponenten des Datums formatiert werden:

Modifikator	Beschreibung
`z`	Nullauffüllung
`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 es die passende Lokalisierung festlegt. Dadurch wird sichergestellt, dass Daten entsprechend den Erwartungen der Benutzer angezeigt und geparst werden.

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, verwenden Sie die Methode setLocale(). Sie akzeptiert eine java.util.Locale und passt sowohl die Formatierung als auch das Parsen automatisch an:

dateField.setLocale(Locale.FRANCE);

Parsing-Logik

Das MaskedDateField parst die Benutzereingabe basierend auf der definierten Datumsmaske. Es akzeptiert sowohl vollständige als auch abgekü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 durch die Maske definierten Formatreihenfolge ab (z. B. %Mz/%Dz/%Yz für Monat/Tag/Jahr). Dieses Format bestimmt, wie numerische Sequenzen interpretiert werden.

Angenommen, heute ist der 15. September 2012, so würden verschiedene Eingaben wie folgt interpretiert werden:

Beispiel-Parsingszenarien

Eingabe	YMD (ISO)	MDY (US)	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-stelliger Monat gefolgt von einer 2-stelligen Tageszahl interpretiert, sodass dies der 12. Januar 2012 wäre.	Gleich wie YMD	Drei Ziffern werden als 1-stelliger Tag 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. Zum Beispiel ist `20040612` der 12. Juni 2004.	Acht Ziffern werden als MMDDYYYY interpretiert. Zum Beispiel ist `06122004` der 12. Juni 2004.	Acht Ziffern werden als DDMMYYYY interpretiert. Zum Beispiel ist `06122004` der 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 werden als gültige Trennzeichen angesehen.	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

Setzen von Min/Max-Beschränkungen

Sie können 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.

Wiederherstellen des Wertes

Das MaskedDateField enthält eine Wiederherstellungsfunktion, die den Wert des Feldes in 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 zum Wiederherstellen des Wertes

Programmgesteuert, durch Aufruf von restoreValue()
Über die Tastatur, durch Drücken von ESC ( dies ist die Standard-Wiederherstelltaste, es sei denn, sie wird von einem Ereignis-Listener überschrieben)

Sie können den Wert, der wiederhergestellt werden soll, mit setRestoreValue() festlegen und eine LocalDate Instanz übergeben.

Code anzeigen

Java

Validierungsmuster

Sie können 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 betrachtet werden.

Format des Regulären Ausdrucks

Das Muster muss der JavaScript-RegExp-Syntax entsprechen, wie hier dokumentiert hier.

Hinweise zur Eingabeverarbeitung

Das Feld versucht, numerische Dateneingaben basierend auf der aktuellen Maske zu parsen und zu formatieren. Benutzer können jedoch weiterhin manuell Werte eingeben, die nicht mit dem erwarteten Format übereinstimmen. Wenn die Eingabe syntaktisch gültig, aber semantisch fehlerhaft oder nicht parsierbar ist (z. B. 99/99/9999), kann sie Mustertests bestehen, aber logische Validierungen nicht bestehen. Sie sollten immer den Eingabewert in Ihrer 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 Kalenderpicker, der es Benutzern ermöglicht, ein Datum visuell auszuwählen, anstatt es einzugeben. Dies verbessert die Benutzerfreundlichkeit für weniger technische Benutzer oder wenn präzise Eingaben erforderlich sind.

Code anzeigen

Java

Zugriff auf den Picker

Sie können auf den Datumsauswähler mit getPicker() zugreifen:

DatePicker picker = dateField.getPicker();

Zeige/Verstecke das Picker-Symbol

Verwenden Sie setIconVisible(), um das Kalendersymbol neben dem Feld ein- oder auszublenden:

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

Automatische Öffnungsverhalten

Sie können den Picker so konfigurieren, dass er automatisch öffnet, wenn der Benutzer mit dem Feld interagiert (z. B. klickt, die Eingabetaste drückt oder Pfeiltasten verwendet):

picker.setAutoOpen(true);

Auswahl über den Picker erzwingen

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

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

Dieses Setup gewährleistet, dass alle Dateneingaben über die Picker-Benutzeroberfläche kommen, was nützlich ist, wenn Sie eine strenge Formatkontrolle wünschen und Parsing-Probleme durch eingegebene Werte vermeiden möchten.

Kalender manuell öffnen

Um den Kalender programmgesteuert zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

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

Wochen im Kalender anzeigen

Der Picker kann optional die Wochennummern in der Kalenderansicht anzeigen:

picker.setShowWeeks(true);