MaskedDateField

Das MaskedDateField ist ein Texteingabefeld, das Benutzern ermöglicht, Daten als Zahlen einzugeben und das Eingabefeld automatisch basierend auf einer definierten Maske zu formatieren, wenn das Feld den Fokus verliert. Die Maske gibt das erwartete Datumsformat vor und leitet sowohl die Eingabe als auch die Anzeige. Die Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wiederherstellung von Werten für eine konsistente, regional spezifische Handhabung von Daten.

Grundlagen

Auf der Suche nach einer Zeiteingabe?

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

Das MaskedDateField kann mit oder ohne Parameter instanziiert werden. Sie können einen Anfangswert, ein Label, einen Platzhalter und einen Ereignislistener für Wertänderungen definieren.

Code anzeigen

Java

Maskenregeln

Das MaskedDateField unterstützt mehrere Datumsformate, die weltweit verwendet werden und je nach Reihenfolge von Tag, Monat und Jahr variieren. Häufige Muster sind:

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

Innerhalb dieser Formate umfasst die lokale Variation die Wahl des Trennzeichens (z.B. -, / oder .), ob Jahre zwei oder vier Ziffern haben und ob einstellig ausgegebene Monate oder Tage mit führenden Nullen gepolstert werden.

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

Datumsformatindikatoren

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

Modifikatoren

Modifikatoren ermöglichen eine größere Kontrolle über die Formatierung von Datumsbestandteilen:

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_maske_ zu erstellen.

Lokalisierung des Datumsformats

Das MaskedDateField passt sich regionalen Datumsformaten an, indem die entsprechende Locale gesetzt wird. Dies stellt sicher, dass Daten so angezeigt und geparst werden, dass sie den Erwartungen der Benutzer entsprechen.

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(). Diese akzeptiert eine java.util.Locale und passt automatisch sowohl die Formatierung als auch das Parsen 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 gewährleistet. Das Parserverhalten hängt von der im Format definierten Reihenfolge 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 folgendermaßen interpretiert:

Beispiel Parsing-Szenarien

Eingabe	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Eine einzelne Ziffer wird immer als Tagesnummer im aktuellen Monat interpretiert, also wäre dies der 1. September 2012.	Dasselbe wie YMD	Dasselbe wie YMD
`12`	Zwei Ziffern werden immer als Tagesnummer im aktuellen Monat interpretiert, also wäre dies der 12. September 2012.	Dasselbe wie YMD	Dasselbe wie YMD
`112`	Drei Ziffern werden als eine 1-stellige Monatsnummer gefolgt von einer 2-stelligen Tagesnummer interpretiert, also wäre dies der 12. Januar 2012.	Dasselbe wie YMD	Drei Ziffern werden als eine 1-stellige Tagesnummer gefolgt von einer 2-stelligen Monatsnummer interpretiert, also wäre dies der 1. Dezember 2012.
`1004`	Vier Ziffern werden als MMDD interpretiert, also wäre dies der 4. Oktober 2012.	Dasselbe wie YMD	Vier Ziffern werden als DDMM interpretiert, also wäre dies der 10. April 2012.
`020304`	Sechs Ziffern werden als YYMMDD interpretiert, also wäre dies der 4. März 2002.	Sechs Ziffern werden als MMDDYY interpretiert, also wäre dies der 3. Februar 2004.	Sechs Ziffern werden als DDMMYY interpretiert, also wäre dies der 2. März 2004.
`8 Ziffern`	Acht Ziffern werden als YYYYMMDD interpretiert. Zum Beispiel, `20040612` entspricht dem 12. Juni 2004.	Acht Ziffern werden als MMDDYYYY interpretiert. Zum Beispiel, `06122004` entspricht dem 12. Juni 2004.	Acht Ziffern werden als DDMMYYYY interpretiert. Zum Beispiel, `06122004` entspricht dem 6. Dezember 2004.
`12/6`	Zwei Zahlen, die durch ein gültiges Trennzeichen getrennt sind, werden als MM/DD interpretiert, also wäre dies der 6. Dezember 2012. Hinweis: Alle Zeichen außer Buchstaben und Ziffern werden als gültige Trennzeichen betrachtet.	Dasselbe wie YMD	Zwei Zahlen, die durch ein Trennzeichen getrennt sind, werden als DD/MM interpretiert, also wäre dies der 12. Juni 2012.
`3/4/5`	5. April 2012	4. März 2005	3. April 2005

Textuelle Datumseingabe 25.11

Standardmäßig akzeptiert das MaskedDateField nur numerische Eingaben für Daten. Sie können jedoch textuelles Datumparsing aktivieren, um Benutzern die Eingabe von Monats- und Tagesnamen zu ermöglichen. Diese Funktion ist besonders nützlich für eine natürlichere Dateneingabe.

Um das textuelle Parsing zu aktivieren, verwenden Sie die Methode setTextualDateParsing():

dateField.setTextualDateParsing(true);

Ersetzung von Monatsnamen

Wenn das textuelle Parsing aktiviert ist, können Sie spezielle Modifikatoren in Ihrer 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 beliebiger 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 - Numerische Fallback funktioniert immer noch

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

Tage-of-week-Namen können in die Eingabe aufgenommen werden, um die Lesbarkeit zu verbessern, sind aber nur dekorativ und werden während des Parsens entfernt. Sie beeinflussen nicht den tatsächlichen Wert des Datums.

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

Tagesnamen erfordern numerische Tage

Wenn Sie Tagesnamen ( %Ds oder %Dl ) verwenden, muss Ihre Maske auch %Dz oder %Dd enthalten, um die tatsächliche Tagesnummer anzugeben. Ohne einen numerischen Tagesbestandteil ist die Eingabe ungültig.

Beispiele

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

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

Das textuelle Datumparsing umfasst mehrere hilfreiche Funktionen:

Groß-/Kleinschreibung ist nicht empfindlich: 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 der konfigurierten Locale des Feldes übereinstimmen. Beispielsweise verwenden Sie bei einer französischen Locale septembre und nicht September. Englische Namen werden nicht erkannt, es sei denn, die Locale ist auf Englisch eingestellt.
- Französische Locale: septembre/01/25 wird als September erkannt
- Deutsche Locale: Montag 09/01/25 wird mit Montag als Tagesname erkannt

Minimale/maximale Einschränkungen festlegen

Sie können den erlaubten Datumsbereich in einem MaskedDateField mithilfe der 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.

Wert wiederherstellen

Das MaskedDateField umfasst eine Wiederherstellungsfunktion, die den Wert des Feldes 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, den Wert wiederherzustellen

Programmgesteuert, durch Aufrufen von restoreValue()
Über die Tastatur, durch Drücken von ESC (dies ist der Standardwiederherstellungsschlüssel, es sei denn, er wird von einem Ereignislistener überschrieben)

Sie können den Wert, auf den zurückgesetzt werden soll, mit setRestoreValue() setzen, wobei eine LocalDate-Instanz übergeben wird.

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 garantiert, 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 regulärer Ausdrücke

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

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, aber semantisch inkorrekt oder nichtparsenbar ist (z.B. 99/99/9999), kann sie Musterprüfungen bestehen, aber logische Validierungen fehlerhaft sein. Sie sollten den Eingabewert in Ihrer Anwendungslogik immer validieren, selbst wenn ein regulärer Ausdrucksmuster festgelegt ist, um sicherzustellen, dass das Datum sowohl korrekt formatiert als auch sinnvoll ist.

Datumsauswähler

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 technische Benutzer oder wenn eine präzise Eingabe erforderlich ist.

Code anzeigen

Java

Zugriff auf den Auswähler

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

DatePicker picker = dateField.getPicker();

Anzeigen/ausblenden des Auswahl-Icons

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

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

Automatische Öffnungsfunktion

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

picker.setAutoOpen(true);

Auswahl über den Auswähler erzwingen

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

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

Diese Konfiguration garantiert, dass alle Datumseingaben über die Benutzeroberfläche des Auswählers erfolgen, was nützlich ist, wenn Sie strenge Formatkontrolle wünschen und Parsing-Probleme aus eingegebenen Daten eliminieren 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 Auswähler kann optional Wochenzahlen in der Kalenderansicht anzeigen:

picker.setShowWeeks(true);