MaskedTimeField

El MaskedTimeField es un campo de texto que permite a los usuarios ingresar horas como números y formatea automáticamente la entrada según 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 análisis flexible, validación, localización y restauración de valores para un manejo consistente del tiempo.

Básicos

¿Buscando entrada de fecha?

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

El MaskedTimeField puede ser instanciado 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

MaskedTimeFieldView.java

Reglas de máscara

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

Aplicar máscaras programáticamente

Para formatear o analizar horas con la misma sintaxis de máscara fuera de un campo, utiliza la clase de utilidad MaskDecorator.

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 de tiempo:

Modificador	Descripción
`z`	Rellenar con ceros
`s`	Representación de texto corta
`l`	Representación de texto larga
`p`	Número empaquetado
`d`	Decimal (formato predeterminado)

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

Localización del formato de tiempo

El MaskedTimeField admite localización configurando la localidad adecuada. Esto garantiza que la entrada y salida de 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 según la máscara de tiempo definida. Acepta entradas numéricas completas y abreviadas con o sin delimitadores, permitiendo una entrada flexible mientras asegura horas válidas. 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`

Estableciendo 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 del tipo java.time.LocalTime. Las entradas fuera del rango definido se consideran inválidas.

Restaurando 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 regresar a una hora predeterminada.

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

Formas 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 sea reemplazada por un oyente de eventos)

Mostrar Código

MaskedTimeFieldRestoreView.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 los valores que coincidan con el formato HH:mm (dos dígitos, dos puntos, dos dígitos) se consideren válidos.

Formato de expresión regular

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

Notas sobre el manejo de entrada

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

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 los usuarios menos técnicos o cuando se requiere una entrada precisa.

Mostrar Código

MaskedTimeFieldPickerView.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 de reloj junto al campo:

picker.setIconVisible(true); // muestra el icono

Comportamiento de apertura automática

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

picker.setAutoOpen(true);

Hacer cumplir la selección a través del selector

Para garantizar que los usuarios solo puedan seleccionar una hora utilizando el selector (y no escribirla 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 entrada de tiempo provenga de la interfaz del selector, lo que es útil cuando deseas un control estricto del formato y eliminar problemas de análisis de las 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()

Configuración del 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 uniformemente una hora o un día completo. De lo contrario, se lanzará una excepción.

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