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

¿Buscas entrada de fecha?

El MaskedTimeField está diseñado para entrada de solo tiempo. Si buscas un componente para manejar fechas con un formato de máscara similar, 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 listener 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 se muestra la hora. Cada indicador de formato comienza con un % seguido de una letra que representa un componente de tiempo.

Aplicando máscaras programáticamente

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

Indicadores de formato de hora

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 compacto
`d`	Decimal (formato predeterminado)

Estos permiten un formateo de tiempo flexible y amigable para locales.

Localización del formato de hora

El MaskedTimeField admite la localización configurando el locale apropiado. Esto asegura 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 en base a la máscara de tiempo definida. Acepta entradas numéricas completas y 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`

Estableciendo restricciones mínimas/máximas

Puedes restringir el rango de tiempo permitido en un MaskedTimeField utilizando 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 definido o original. Esto puede ser útil para deshacer cambios o volver 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 se sobrescriba por un listener de eventos)

Mostrar Código

MaskedTimeFieldRestoreView.java

Patrones de validación

Puedes aplicar reglas de validación del lado del cliente utilizando 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 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 inaplicable (por ejemplo, 99:99), puede pasar las verificaciones 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 asegurar que el tiempo esté correctamente formateado y 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 del reloj al lado del 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úa con el campo (por ejemplo, hace clic, presiona Enter o las teclas de flecha):

picker.setAutoOpen(true);

Forzar Selección a Través del Selector

Para asegurar que los usuarios solo puedan seleccionar una hora usando el selector (y no escribir manualmente una), 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 cual 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 utiliza el alias:

picker.show(); // lo mismo que open()

Estableciendo el paso del selector

Puedes definir el intervalo entre las horas seleccionables en el selector utilizando setStep(). Esto te permite controlar qué tan 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 asegura que la lista desplegable contenga valores predecibles y espaciados uniformemente como 09:00, 09:15, 09:30, etc.