MaskedDateField

Das MaskedDateField ist ein Texteingabefeld, das es Benutzern ermöglicht, Daten als Zahlen einzugeben und die Eingabe 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 die Wiederherstellung von Werten für eine konsistente, regionsspezifische Datumsbehandlung.

Grundlagen

Suchen Sie nach einer Zeiteingabe?

Das MaskedDateField konzentriert sich ausschließlich auf Datumswerte. Wenn Sie eine ähnliche Komponente zum Eingeben und Formatieren 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

MaskedDateFieldView.java

Maskenregeln

Das MaskedDateField unterstützt mehrere Datumsformate, die weltweit verwendet werden und sich nach der Reihenfolge von Tag, Monat und Jahr unterscheiden. 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 gibt es lokale Variationen wie die Wahl des Trennzeichens (z. B. -, / oder .), ob Jahre zwei oder vier Ziffern haben und ob einstellige Monate oder Tage mit führenden Nullen erweitert werden.

Um mit dieser Vielfalt umzugehen, verwendet das MaskedDateField Formatindikatoren, die jeweils mit % beginnen, gefolgt von einem Buchstaben, der einen spezifischen Teil des Datums darstellt. Diese Indikatoren definieren, wie die Eingabe geparsed und wie das Datum angezeigt wird.

Anwendung von Masken programmgesteuert

Um Daten mit der gleichen Maskensyntax außerhalb eines Feldes zu formatieren oder zu parsen, verwenden Sie die MaskDecorator Utility-Klasse.

Datumsformatindikatoren

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

Modifizierer

Modifizierer erlauben eine genauere Kontrolle darüber, wie die Komponenten des Datums formatiert werden:

Modifizierer	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 Datumsmasken zu erstellen.

Lokalisierung des Datumsformats

Das MaskedDateField passt sich regionalen Datumsformaten an, indem es die geeignete Gebietsschemaeinstellung festlegt. Dies stellt sicher, dass Daten in einer Weise angezeigt und geparsed 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, verwenden Sie die Methode setLocale(). Diese akzeptiert ein java.util.Locale und passt automatisch sowohl Formatierung als auch Parsing an:

dateField.setLocale(Locale.FRANCE);

Parsing-Logik

Das MaskedDateField parsed 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, während gültige Daten sichergestellt werden. Das Parsing-Verhalten hängt von der durch die Maske definierten Formatordnung ab (z. B. %Mz/%Dz/%Yz für Monat/Tag/Jahr). Dieses Format bestimmt, wie numerische Sequenzen interpretiert werden.

Angenommen, heute ist 15. September 2012, so würden verschiedene Eingaben folgendermaßen interpretiert werden:

Beispiel-Parsingszenarien

Eingabe	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Eine einzelne Ziffer wird immer als Tag im aktuellen Monat interpretiert, also wäre das der 1. September 2012.	Gleich wie YMD	Gleich wie YMD
`12`	Zwei Ziffern werden immer als Tag im aktuellen Monat interpretiert, also wäre das der 12. September 2012.	Gleich wie YMD	Gleich wie YMD
`112`	Drei Ziffern werden als 1-stellige Monatszahl gefolgt von einer 2-stelligen Tageszahl interpretiert, also wäre das der 12. Januar 2012.	Gleich wie YMD	Drei Ziffern werden als 1-stellige Tageszahl gefolgt von einer zweistelligen Monatszahl interpretiert, also wäre das der 1. Dezember 2012.
`1004`	Vier Ziffern werden als MMDD interpretiert, also wäre das der 4. Oktober 2012.	Gleich wie YMD	Vier Ziffern werden als DDMM interpretiert, also wäre das der 10. April 2012.
`020304`	Sechs Ziffern werden als YYMMDD interpretiert, also wäre das der 4. März 2002.	Sechs Ziffern werden als MMDDYY interpretiert, also wäre das der 3. Februar 2004.	Sechs Ziffern werden als DDMMYY interpretiert, also wäre das der 2. März 2004.
`8 Ziffern`	Acht Ziffern werden als YYYYMMDD interpretiert. Zum Beispiel, `20040612` ist der 12. Juni 2004.	Acht Ziffern werden als MMDDYYYY interpretiert. Zum Beispiel, `06122004` ist der 12. Juni 2004.	Acht Ziffern werden als DDMMYYYY interpretiert. Zum Beispiel, `06122004` ist der 6. Dezember 2004.
`12/6`	Zwei Zahlen, die durch ein gültiges Trennzeichen getrennt sind, werden als MM/DD interpretiert, also wäre das der 6. Dezember 2012. 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, also wäre das der 12. Juni 2012.
`3/4/5`	5. April 2012	4. März 2005	3. April 2005

Textuelles Datumsparsing 25.11

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

Um textuelles Parsen zu aktivieren, verwenden Sie die Methode setTextualDateParsing():

dateField.setTextualDateParsing(true);

Monatsnamenersatz

Wenn textuelles Parsen aktiviert ist, können Sie spezielle Modifizierer 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 - Parse als 1. September 2025
`%Ml/%Dz/%Yz`	`September/01/25`	Gültig - Parse als 1. September 2025
`%Dz/%Ml/%Yz`	`01/September/25`	Gültig - Parse als 1. September 2025
`%Mz/%Dz/%Yz`	`09/01/25`	Gültig - Numerisches 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

Tage der Woche können in die Eingabe aufgenommen werden, um die Lesbarkeit zu verbessern, aber sie sind nur dekorativ und werden beim Parsen 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 numerischen Tag

Wenn Sie Tagesnamen ( %Ds oder %Dl) verwenden, muss Ihre Maske auch %Dz oder %Dd enthalten, um die tatsächliche Tageszahl anzugeben. Ohne eine numerische Tageskomponente 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 - Fehlender `%Dz`
`%Mz/%Dl/%Yz`	`09/Montag/25`	Ungültig - Fehlender `%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 Datumsparsing umfasst mehrere hilfreiche Funktionen:

Groß- und Kleinschreibung ignoriert: Eingaben wie MONTAG 09/01/25, montag 09/01/25 oder Montag 09/01/25 funktionieren alle gleich.
Lokal abhängig: Monats- und Tagesnamen müssen mit dem konfigurierten Gebietsschema des Feldes übereinstimmen. Beispielsweise müssen Sie bei einer französischen Gebietsschemaeinstellung septembre und nicht September verwenden. 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.

Festlegen von Min-/Max-Beschränkungen

Sie können den zulässigen 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 gelten als ungültig.

Wiederherstellen des Wertes

Das MaskedDateField umfasst 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 Aufruf von restoreValue()
Über die Tastatur, indem Sie ESC drücken (dies ist die Standard-Wiederherstellungstaste, es sei denn, sie wird von einem Ereignislistener überschrieben)

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

Code anzeigen

MaskedDateFieldRestoreView.java

Validierungsmuster

Sie können clientseitige Validierungsregeln mithilfe regulärer Ausdrücke 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 regulärer Ausdrücke

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

Hinweise zur Eingabeverarbeitung

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

Datumsauswahl

Das MaskedDateField enthält einen integrierten Kalenderauswahl, 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

MaskedDateFieldPickerView.java

Zugriff auf den Picker

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

DatePicker picker = dateField.getPicker();

Anzeigen/Verstecken des Picker-Icons

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

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

Automatisches Öffnungsverhalten

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

picker.setAutoOpen(true);

Erzwingen der Auswahl über den Picker

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

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

Diese Einrichtung garantiert, dass alle Datumseingaben über die Picker-Benutzeroberfläche erfolgen, was nützlich ist, wenn Sie strenge Formatkontrolle möchten und Parsing-Probleme von eingetippten Eingaben eliminieren möchten.

Kalender manuell öffnen

Um den Kalender programmgesteuert zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

picker.show(); // dasselbe wie öffnen

Kalenderwochen anzeigen

Der Picker kann optional die Wochennummern in der Kalenderansicht anzeigen:

picker.setShowWeeks(true);