MaskedTimeField

Das MaskedTimeField ist ein Texteingabefeld, das Benutzern das Eingeben von Zeiten als Zahlen ermöglicht und die Eingabe automatisch anhand einer definierten Maske formatiert, wenn das Feld den Fokus verliert. Die Maske gibt das erwartete Zeitformat vor und weist sowohl bei der Eingabe als auch bei der Anzeige den richtigen Weg. Die Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wiederherstellung von Werten für eine konsistente Zeitbehandlung.

Grundlagen

Suchen Sie nach einer Datums-Eingabe?

Das MaskedTimeField ist für nur Zeit Eingaben konzipiert. Wenn Sie nach einer Komponente suchen, die Daten mit ähnlicher maskenbasierter Formatierung verwaltet, sehen Sie sich das MaskedDateField an.

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

Code anzeigen

MaskedTimeFieldView.java

Maskenregeln

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

Masken programmatisch anwenden

Um Zeiten mit derselben Maskensyntax außerhalb eines Feldes zu formatieren oder zu parsen, verwenden Sie die MaskDecorator Dienstklasse.

Zeitformatindikatoren

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

Modifikatoren

Modifikatoren verfeinern die Anzeige von Zeitkomponenten:

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

Diese ermöglichen eine flexible und lokal freundliche Zeitformatierung.

Lokalisierung des Zeitformats

Das MaskedTimeField unterstützt die Lokalisierung durch das Setzen der entsprechenden Sprache. Dies stellt sicher, dass die Zeiteingaben und -ausgaben den regionalen Konventionen entsprechen.

field.setLocale(Locale.GERMANY);

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

Parsing-Logik

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

Beispiel-Parszenarien

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`

Min-/Max-Beschränkungen festlegen

Sie können den zulässigen Zeitbereich in einem MaskedTimeField mithilfe der setMin()- und setMax()-Methoden 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 werden als ungültig angesehen.

Wert wiederherstellen

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, den Wert wiederherzustellen

Programmatisch, durch Aufrufen von restoreValue()
Über die Tastatur, durch Drücken von ESC (dies ist die Standard-Wiederherstelltaste, es sei denn, sie wird durch einen Event-Listener überschrieben)

Code anzeigen

MaskedTimeFieldRestoreView.java

Validierungsmuster

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

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

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

Format für reguläre Ausdrücke

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 parsierbar ist (z. B. 99:99), kann sie das Muster durchlaufen, jedoch bei der logischen Validierung fehlschlagen. Sie sollten den Eingabewert in Ihrer Anwendungslogik immer validieren, auch wenn ein reguläres Ausdrucksmuster 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 einzutippen. Dies verbessert die Benutzerfreundlichkeit für weniger technische Benutzer oder wenn eine präzise Eingabe erforderlich ist.

Code anzeigen

MaskedTimeFieldPickerView.java

Zugriff auf den Picker

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

TimePicker picker = field.getPicker();

Picker-Icon einblenden/ausblenden

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

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

Automatische Öffnungsfunktion

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

picker.setAutoOpen(true);

Auswahl über den Picker erzwingen

Um sicherzustellen, dass Benutzer nur eine Zeit ü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 Benutzerinteraktion
field.setAllowCustomValue(false);     // Deaktiviert die manuelle Texteingabe

Diese Konfiguration stellt sicher, dass alle Zeiteingaben über die Picker-Benutzeroberfläche erfolgen, was nützlich ist, wenn Sie eine strikte Formatkontrolle wünschen und Parsing-Probleme durch eingegebene Werte beseitigen möchten.

Picker manuell öffnen

Um den Zeitpicker programmatisch zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

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

Schritt des Pickers festlegen

Sie können das Intervall zwischen wählbaren Zeiten im Picker mit setStep() definieren. Damit können Sie steuern, wie detailliert die Zeitoptionen sind – ideal für Szenarien wie die Planung in 15-Minuten-Intervallen.

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

Schritt-Beschränkung

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

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