MaskedTimeField

Das MaskedTimeField ist ein Texteingabefeld, das für präzise, strukturierte Zeiteingaben konzipiert ist. Es ermöglicht den Benutzern, Zeiten als Zahlen einzugeben, und formatiert die Eingabe automatisch basierend auf einer definierten Maske, wenn das Feld den Fokus verliert. Die Maske ist eine Zeichenfolge, die das erwartete Zeitformat angibt und sowohl Eingabe als auch Anzeige lenkt.

Diese Komponente unterstützt flexible Parsing-, Validierungs-, Lokalisierungs- und Wertwiederherstellungsfunktionen. Sie ist besonders nützlich bei zeitkritischen Formularen wie Zeitplänen, Stundenzetteln und Reservierungen.

Suchen Sie ein Datumseingabefeld?

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

Grundlagen

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

Java

Maskenregeln

Das MaskedTimeField verwendet Formatindikatoren, um zu definieren, wie die Zeit geparsed und angezeigt wird. 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

Modifikatoren

Modifikatoren verfeinern die Anzeige von Zeitkomponenten:

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

Diese ermöglichen eine flexible und ortsunabhängige Zeitformatierung.

Lokalisierung des Zeitformats

Das MaskedTimeField unterstützt die Lokalisierung, indem die entsprechende Locale gesetzt wird. Dies stellt sicher, dass die zeitliche Eingabe und Ausgabe 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 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 eine flexible Eingabe, während gültige Zeiten sichergestellt werden. 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-Parsingszenarien

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 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 werden als ungültig betrachtet.

Den Wert wiederherstellen

Das MaskedTimeField umfasst 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();

Arten der Wiederherstellung des Wertes

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

Code anzeigen

Java

Validierungsmuster

Sie können clientseitige Validierungsregeln mit regulären Ausdrücken über die Methode setPattern() anwenden:

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

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

Format des regulären Ausdrucks

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

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 unparsebar ist (z.B. 99:99), kann sie Musterprüfungen bestehen, aber die logische Validierung fehlschlagen. Sie sollten den Eingabewert in Ihrer Anwendungslogik immer validieren, selbst wenn ein regulärer Ausdruck festgelegt ist, um sicherzustellen, dass die Zeit sowohl korrekt formatiert als auch sinnvoll ist.

Zeitwähler

Das MaskedTimeField umfasst einen integrierten Zeitwähler, der es Benutzern ermöglicht, eine Zeit visuell auszuwählen, anstatt sie einzutippen. Dies verbessert die Benutzerfreundlichkeit für weniger technische Nutzer oder wenn eine präzise Eingabe erforderlich ist.

Code anzeigen

Java

Zugriff auf den Wähler

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

TimePicker picker = field.getPicker();

Wählen/Verstecken des Wähler-Icons

Verwenden Sie setIconVisible(), um das Uhr-Icon neben dem Feld anzuzeigen oder zu verbergen:

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

Auto-öffnen Verhalten

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

picker.setAutoOpen(true);

Auswahl über den Wähler erzwingen

Um sicherzustellen, dass Benutzer eine Zeit nur über den Wähler auswählen können (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ählerschnittstelle erfolgen, was hilfreich ist, wenn Sie eine strenge Formatkontrolle wünschen und Parsing-Probleme durch getippte Eingaben ausschließen möchten.

Wähler manuell öffnen

Um den Zeitwähler programmgesteuert zu öffnen:

picker.open();

Oder verwenden Sie das Alias:

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

Einstellung des Schrittwerts des Wählers

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

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

Schrittbeschränkung

Der Schritt muss gleichmäßig eine Stunde oder einen ganzen Tag 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.