MaskedTimeField

Das MaskedTimeField ist ein Texteingabefeld, das es Benutzern ermöglicht, Zeiten 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 Zeitformat an, das sowohl die Eingabe als auch die Anzeige steuert. Die Komponente unterstützt flexibles Parsen, Validierung, Lokalisierung und Wertwiederherstellung für einen konsistenten Umgang mit Zeiten.

Grundlagen

Suchen Sie nach einem Datumsfeld?

Das MaskedTimeField ist für die nur Zeit Eingabe konzipiert. Wenn Sie eine Komponente suchen, die Datumsangaben 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 anfänglichen Wert, 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 Zeitkomponente darstellt.

Masken programmgesteuert anwenden

Um Zeiten mit der gleichen 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

Modifizierer

Modifizierer verfeinern die Anzeige von Zeitkomponenten:

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

Diese ermöglichen eine flexible und locale-freundliche Zeitformatierung.

Lokalisierung des Zeitformats

Das MaskedTimeField unterstützt die Lokalisierung durch Setzen der entsprechenden Locale. Dies stellt sicher, dass Eingabe und Ausgabe der Zeit den regionalen Konventionen entsprechen.

field.setLocale(Locale.GERMANY);

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

Parsing-Logik

Das MaskedTimeField parsed die Benutzereingabe 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 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 für 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 mithilfe der 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.

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

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

Code anzeigen

MaskedTimeFieldRestoreView.java

Validierungsmuster

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

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

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 den Musterprüfungen standhalten, aber die logische Validierung scheitern. Sie sollten den Eingabewert in der Logik Ihrer App immer validieren, auch wenn ein reguläres Ausdrucksmuster gesetzt ist, um sicherzustellen, dass die Zeit sowohl korrekt formatiert als auch sinnvoll ist.

Zeitwähler

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

Code anzeigen

MaskedTimeFieldPickerView.java

Zugriff auf den Wähler

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

TimePicker picker = field.getPicker();

Anzeigen/ausblenden des Wähler-Icons

Verwenden Sie setIconVisible(), um das Uhren-Icon neben dem Feld anzuzeigen oder auszublenden:

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

Automatisches Öffnungsverhalten

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

picker.setAutoOpen(true);

Erzwingen der Auswahl über den Wähler

Um sicherzustellen, dass Benutzer eine Zeit nur ü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 gewährleistet, dass alle Zeiteingaben über die Wähler-UI erfolgen, was nützlich ist, wenn Sie strenge Formatkontrolle wünschen und Parsing-Probleme durch manuelle Eingaben vermeiden möchten.

Manuell den Wähler öffnen

Um den Zeitwähler programmgesteuert zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

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

Festlegen des Schrittes des Wählers

Sie können das Intervall zwischen wählbaren Zeiten im Wähler mit setStep() definieren. Dies ermöglicht es Ihnen, wie granular die Zeitoptionen sind - ideal für Szenarien wie die Planung in 15-Minuten-Intervallen.

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

Schrittbeschränkung

Der Schritt muss eine volle 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.