MaskedTimeField

El MaskedTimeField es un campo de texto que permite a los usuarios ingresar horas como números y automáticamente formatea la entrada en base a una máscara definida cuando el campo pierde el foco. La máscara especifica el formato de hora esperado, guiando tanto la entrada como la visualización. El componente admite un análisis, validación, localización y restauración de valores flexibles para un manejo consistente del tiempo.

Básicos

¿Buscas una entrada de fecha?

El MaskedTimeField está diseñado para entrada de solo tiempo. Si buscas un componente que maneje fechas con un formato basado en máscara similar, echa un vistazo al MaskedDateField.

El MaskedTimeField se puede instanciar con o sin parámetros. Puedes definir un valor inicial, una etiqueta, un marcador de posición y un oyente de eventos para cambios de valor.

Mostrar Código

Java

Reglas de máscara

El MaskedTimeField utiliza indicadores de formato para definir cómo se analiza y se muestra el tiempo. Cada indicador de formato comienza con un % seguido de una letra que representa un componente de tiempo.

Indicadores de formato de tiempo

Formato	Descripción
`%H`	Hora (24 horas)
`%h`	Hora (12 horas)
`%m`	Minuto
`%s`	Segundo
`%p`	AM/PM

Modificadores

Los modificadores refinan la visualización de los componentes del tiempo:

Modificador	Descripción
`z`	Rellenar con ceros
`s`	Representación de texto corto
`l`	Representación de texto largo
`p`	Número empaquetado
`d`	Decimal (formato por defecto)

Estos permiten un formato de tiempo flexible y amigable con la localidad.

Localización del formato de tiempo

El MaskedTimeField admite la localización al establecer la localidad apropiada. Esto asegura que la entrada y salida del tiempo coincidan con las convenciones regionales.

field.setLocale(Locale.GERMANY);

Esto afecta cómo se muestran los indicadores AM/PM, cómo se manejan los separadores y cómo se analizan los valores.

Lógica de análisis

El MaskedTimeField analiza la entrada del usuario en función de la máscara de tiempo definida. Acepta tanto entradas numéricas completas como abreviadas con o sin delimitadores, permitiendo una entrada flexible mientras asegura tiempos válidos. El comportamiento de análisis depende del orden de formato definido por la máscara (por ejemplo, %Hz:%mz para hora/minuto). Este formato determina cómo se interpretan las secuencias numéricas.

Ejemplos de escenarios de análisis

Entrada	Máscara	Interpretado Como
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Establecer restricciones mínimas/máximas

Puedes restringir el rango de tiempo permitido en un MaskedTimeField usando los métodos setMin() y setMax():

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

Ambos métodos aceptan valores de tipo java.time.LocalTime. Las entradas fuera del rango definido se consideran inválidas.

Restaurar el valor

El MaskedTimeField incluye una función de restauración que restablece el valor del campo a un estado predefinido u original. Esto puede ser útil para deshacer cambios o volver a un tiempo predeterminado.

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

Maneras de restaurar el valor

Programáticamente, llamando a restoreValue()
A través del teclado, presionando ESC (esta es la tecla de restauración predeterminada a menos que se sobrescriba por un oyente de eventos)

Mostrar Código

Java

Patrones de validación

Puedes aplicar reglas de validación del lado del cliente usando expresiones regulares con el método setPattern():

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

Este patrón asegura que solo se consideren válidos los valores que coincidan con el formato HH:mm (dos dígitos, dos puntos, dos dígitos).

Formato de Expresión Regular

El patrón debe seguir la sintaxis de RegExp de JavaScript como se documenta aquí.

Notas sobre el Manejo de Entrada

El campo intenta analizar y formatear las entradas numéricas de tiempo según la máscara actual. Sin embargo, los usuarios aún pueden ingresar manualmente valores que no coinciden con el formato esperado. Si la entrada es sintácticamente válida pero semánticamente incorrecta o no analizable (por ejemplo, 99:99), puede pasar los chequeos de patrón pero fallar en la validación lógica. Siempre debes validar el valor ingresado en la lógica de tu aplicación, incluso si se establece un patrón de expresión regular, para asegurar que el tiempo esté correctamente formateado y sea significativo.

Selector de tiempo

El MaskedTimeField incluye un selector de tiempo incorporado que permite a los usuarios seleccionar una hora visualmente, en lugar de escribirla. Esto mejora la usabilidad para usuarios menos técnicos o cuando se requiere una entrada precisa.

Mostrar Código

Java

Accediendo al selector

Puedes acceder al selector de tiempo usando getPicker():

TimePicker picker = field.getPicker();

Mostrar/ocultar el ícono del selector

Usa setIconVisible() para mostrar u ocultar el ícono del reloj junto al campo:

picker.setIconVisible(true); // muestra el ícono

Comportamiento de apertura automática

Puedes configurar el selector para que se abra automáticamente cuando el usuario interactúe con el campo (por ejemplo, haga clic, presione Enter o las teclas de flecha):

picker.setAutoOpen(true);

Hacer Cumplir la Selección a Través del Selector

Para asegurar que los usuarios solo puedan seleccionar una hora usando el selector (y no escribir una manualmente), combina las siguientes dos configuraciones:

field.getPicker().setAutoOpen(true); // Abre el selector en la interacción del usuario
field.setAllowCustomValue(false);    // Desactiva la entrada de texto manual

Esta configuración garantiza que toda la entrada de tiempo provenga a través de la interfaz del selector, lo que es útil cuando deseas un control estricto sobre el formato y eliminar problemas de análisis de entradas escritas.

Abrir manualmente el selector

Para abrir el selector de tiempo programáticamente:

picker.open();

O usa el alias:

picker.show(); // igual que open()

Establecer el paso del selector

Puedes definir el intervalo entre los tiempos seleccionables en el selector usando setStep(). Esto te permite controlar cuán granular son las opciones de tiempo, ideal para escenarios como la programación en bloques de 15 minutos.

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

Restricción de paso

El paso debe dividir de manera uniforme una hora o un día completo. De lo contrario, se lanzará una excepción.

Esto asegura que la lista desplegable contenga valores predecibles y espaciados uniformemente como 09:00, 09:15, 09:30, etc.