MaskedTimeField

Das MaskedTimeField ist ein Texteingabefeld, mit dem Benutzer Zeiten als Zahlen eingeben können, und formatiert die Eingabe automatisch basierend auf einer definierten Maske, wenn das Feld den Fokus verliert. Die Maske gibt das erwartete Zeitformat an, welches sowohl die Eingabe als auch die Anzeige leitet. Die Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wiederherstellung von Werten für eine konsistente Zeitverarbeitung.

Grundlagen

Suchen Sie ein Datumsfeld?

Das MaskedTimeField ist für nur Zeit Eingaben konzipiert. Wenn Sie nach einer Komponente suchen, die Daten mit ähnlicher maskenbasierter Formatierung verarbeitet, werfen Sie einen Blick auf das MaskedDateField.

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

Code anzeigen

Java

Maskenregeln

Das MaskedTimeField verwendet Formatindikatoren, um zu definieren, wie Zeiten geparst und angezeigt werden. Jeder Formatindikator beginnt mit einem %, gefolgt von einem Buchstaben, der eine Zeitkomponente darstellt.

Zeitformatindikatoren

Format	Beschreibung
`%H`	Stunde (24-Stunden)
`%h`	Stunde (12-Stunden)
`%m`	Minute
`%s`	Sekunde
`%p`	AM/PM

Modifizierer

Modifizierer verfeinern die Anzeige von Zeitkomponenten:

Modifizierer	Beschreibung
`z`	Nullfüllung
`s`	Kurze Textdarstellung
`l`	Lange Textdarstellung
`p`	Gepackte Zahl
`d`	Dezimal (Standardformat)

Diese ermöglichen eine flexible und lokalisierungsfreundliche Zeitformatierung.

Lokalisierung des Zeitformats

Das MaskedTimeField unterstützt die Lokalisierung, indem das entsprechende Gebietsschema gesetzt wird. Dies sorgt dafür, dass Eingabe und Ausgabe der Zeit mit regionalen Konventionen übereinstimmen.

field.setLocale(Locale.GERMANY);

Dies beeinflusst, wie AM/PM-Indikatoren angezeigt werden, wie Trenner behandelt werden und wie Werte geparst werden.

Parsing-Logik

Das MaskedTimeField parst die Benutzereingabe basierend auf der definierten Zeitmaske. Es akzeptiert sowohl vollständige als auch abgekürzte numerische Eingaben mit oder ohne Trennzeichen und ermöglicht damit eine flexible Eingabe, wobei dennoch gültige Zeiten sichergestellt werden. Das Parsing-Verhalten hängt von der Formatreihenfolge ab, die durch die Maske definiert wird (z.B. %Hz:%mz für Stunde/Minute). Dieses Format bestimmt, wie numerische Sequenzen interpretiert werden.

Beispielhafte Parsing-Szenarien

Eingabe	Maske	Interpretiert Als
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Einstellung von Min/Max-Beschränkungen

Sie können den erlaubten Zeitrahmen in einem MaskedTimeField mit den Methoden setMin() und setMax() einschränken:

field.setMin(LocalTime.of(8, 0));
field.setMax(LocalTime.of(18, 0));

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

Wiederherstellung des Wertes

Das MaskedTimeField verfügt über eine Wiederherstellungsfunktion, die den Wert des Feldes auf einen vordefinierten oder ursprünglichen Zustand zurücksetzt. Dies kann nützlich sein, um Änderungen rückgängig zu machen oder zu einer Standardzeit zurückzukehren.

field.setRestoreValue(LocalTime.of(12, 0));
field.restoreValue();

Möglichkeiten zur Wiederherstellung des Wertes

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

Code anzeigen

Java

Validierungsmuster

Sie können clientseitige Validierungsregeln mithilfe von regulären Ausdrücken mit der Methode setPattern() anwenden:

field.setPattern("^\\d{2}:\\d{2}$");

Dieses Muster stellt sicher, dass nur Werte, die dem Format HH:mm (zwei Ziffern, Doppelpunkt, zwei Ziffern) entsprechen, als gültig betrachtet werden.

Format des Regulären Ausdrucks

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

Hinweise zur Eingabeverarbeitung

Das Feld versucht, numerische Zeiteingaben 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 nicht parsebar ist (z.B. 99:99), kann sie die Mustertests bestehen, aber die logische Validierung fehlschlagen. Sie sollten den Eingabewert in Ihrer Anwendungslogik immer validieren, auch wenn ein Muster mit regulärem Ausdruck gesetzt ist, um sicherzustellen, dass die Zeit sowohl korrekt formatiert als auch sinnvoll ist.

Zeitpicker

Das MaskedTimeField enthält einen integrierten Zeitpicker, der es Benutzern ermöglicht, eine Zeit visuell auszuwählen, anstatt sie einzugeben. Dies verbessert die Benutzerfreundlichkeit für weniger technische Benutzer oder wenn eine präzise Eingabe erforderlich ist.

Code anzeigen

Java

Zugriff auf den Picker

Sie können auf den Zeitpicker mit getPicker() zugreifen:

TimePicker picker = field.getPicker();

Anzeigen/Verbergen des Picker-Icons

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

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

Auto-Öffnungs-Verhalten

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 Pfeiltasten verwendet):

picker.setAutoOpen(true);

Auswahl über den Picker erzwingen

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

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

Dieses Setup gewährleistet, dass alle Zeiteingaben über die Picker-Benutzeroberfläche erfolgen, was nützlich ist, wenn Sie strenge Formatkontrolle wünschen und Parsing-Probleme bei eingegebener Eingabe vermeiden möchten.

Manuelles Öffnen des Pickers

Um den Zeitpicker programmgesteuert zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

picker.show(); // entspricht open()

Schritt des Pickers einstellen

Sie können das Intervall zwischen wählbaren Zeiten im Picker mit setStep() festlegen. Dadurch können Sie steuern, wie granular die Zeitoptionen sind – ideal für Szenarien wie die Planung in 15-Minuten-Blöcken.

field.getPicker().setStep(Duration.ofMinutes(15));

Schritt-Beschränkung

Der Schritt muss eine Stunde oder einen gesamten Tag gleichmäßig teilen. Andernfalls wird eine Ausnahme ausgelöst.

Dies sorgt dafür, dass die Dropdown-Liste vorhersehbare, gleichmäßig verteilte Werte wie 09:00, 09:15, 09:30 usw. enthält.