MaskedTimeField

Das MaskedTimeField ist ein Texteingabefeld, das es Benutzern ermöglicht, Zeiten 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 Zeitformat an und dient sowohl der Eingabe als auch der Anzeige als Leitfaden. Die Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wertwiederherstellung für eine konsistente Zeitverarbeitung.

Suchen Sie ein Datumseingabefeld?

Das MaskedTimeField ist für nur Zeit Eingaben konzipiert. Wenn Sie eine Komponente suchen, die Datumsangaben mit ähnlicher maskenbasierter Formatierung behandelt, 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 Wertänderungen definieren.

Code anzeigen

MaskedTimeFieldView.java

Maskenregeln

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

Masken programmatisch anwenden

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

Zeitformatindikatoren

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

Modifikatoren

Modifikatoren verfeinern die Darstellung von Zeiteinheiten:

Modifikator	Beschreibung
`z`	Nullauffüllen
`s`	Kurze Textdarstellung
`l`	Lange Textdarstellung
`p`	Kompakte Zahl
`d`	Dezimal (Standardformat)

Diese ermöglichen eine flexible und lokalisierungsfreundliche Zeitformatierung.

Lokalisierung des Zeitformats

Das MaskedTimeField unterstützt die Lokalisierung durch Setzen der entsprechenden Locale. Dies stellt sicher, dass Eingaben und Ausgaben von Zeiten regionalen Konventionen entsprechen.

field.setLocale(Locale.GERMANY);

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

Parsing-Logik

Das MaskedTimeField parsed Benutzereingaben basierend auf der definierten Zeitmaske. 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 Zeiten sichert. 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.

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`

Minimale/maximale Einschränkungen festlegen

Sie können den erlaubten Zeitbereich 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 des Typs java.time.LocalTime. Eingaben außerhalb des definierten Bereichs werden als ungültig betrachtet.

Wiederherstellung des Wertes

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

Programmatisch, durch Aufruf von restoreValue()
Über die Tastatur, durch Drücken von ESC (dies ist die standardmäßige Wiederherstellungstaste, es sei denn, sie wird von einem Ereignislistener überschrieben)

Code anzeigen

MaskedTimeFieldRestoreView.java

Validierungsmuster

Sie können clientseitige Validierungsregeln mit regulären Ausdrücken unter Verwendung 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 für reguläre Ausdrücke

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

Hinweise zur Eingabeverarbeitung

Das Feld versucht, numerische Zeitwerte 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 Prüfungsmuster bestehen, aber bei logischen Validierungen fehlschlagen. Sie sollten den Eingabewert in Ihrer Anwendungslogik immer validieren, selbst wenn ein reguläres Ausdrucksmuster festgelegt ist, um sicherzustellen, dass die Zeit sowohl korrekt formatiert als auch sinnvoll ist.

Zeitwähler

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

Code anzeigen

MaskedTimeFieldPickerView.java

Zugriff auf den Wähler

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

TimePicker picker = field.getPicker();

Anzeige/Verstecken des Wähler-Icons

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

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

Automatisches Öffnungsverhalten

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

picker.setAutoOpen(true);

Auswahl über den Wähler erzwingen

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

field.getPicker().setAutoOpen(true); // Öffnet den Wähler bei Benutzerinteraktion
field.setAllowCustomValue(false);     // Deaktiviert die manuelle Texteingabe

Diese Konfiguration garantiert, dass alle Zeiteingaben über die Wähler-Benutzeroberfläche erfolgen, was nützlich ist, wenn Sie eine strenge Formatkontrolle wünschen und Parsing-Probleme bei manuell eingegebene Werte ausschließen möchten.

Wähler manuell öffnen

Um den Zeitwähler programmatisch zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

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

Einstellung des Wähler-Schrittes

Sie können das Intervall zwischen auswählbaren Zeiten im Wähler mithilfe von setStep() definieren. Dies ermöglicht Ihnen, die Granularität der Zeitoptionen zu steuern – ideal für Szenarien wie die Planung in 15-Minuten-Intervallen.

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

Schrittbegrenzung

Der Schritt muss eine vollständige Stunde oder einen vollen 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.