MaskedDateField

El MaskedDateField es un control de entrada de texto diseñado para la entrada estructurada de fechas. Permite a los usuarios ingresar fechas como números y formatea automáticamente la entrada según una máscara definida cuando el campo pierde el foco. La máscara es una cadena que especifica el formato de fecha esperado, guiando tanto la entrada como la visualización.

Este componente soporta análisis flexible, validación, localización y restauración de valores. Es especialmente útil en formularios como registros, reservas y programación, donde se requieren formatos de fecha consistentes y específicos de la región.

¿Buscas entrada de tiempo?

El MaskedDateField se centra exclusivamente en valores de fecha. Si necesitas un componente similar para ingresar y formatear tiempo, consulta el MaskedTimeField en su lugar.

Basics

El MaskedDateField 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 los cambios de valor.

Mostrar Código

Java

Mask rules

El MaskedDateField soporta múltiples formatos de fecha utilizados en todo el mundo, que varían por el orden de día, mes y año. Los patrones comunes incluyen:

Día/Mes/Año (utilizado en la mayor parte de Europa)
Mes/Día/Año (utilizado en los Estados Unidos)
Año/Mes/Día (utilizado en China, Japón y Corea; también el estándar ISO: YYYY-MM-DD)

Dentro de estos formatos, las variaciones locales incluyen la elección del separador (por ejemplo, -, / o .), si los años son de dos o cuatro dígitos, y si los meses o días de un solo dígito tienen ceros delante.

Para manejar esta diversidad, el MaskedDateField utiliza indicadores de formato, cada uno comenzando con %, seguido de una letra que representa una parte específica de la fecha. Estos indicadores definen cómo se analiza la entrada y cómo se muestra la fecha.

Date format indicators

Formato	Descripción
`%Y`	Año
`%M`	Mes
`%D`	Día

Modifiers

Los modificadores permiten un mayor control sobre cómo se formatean los componentes de la fecha:

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

Estos pueden combinarse para construir una amplia variedad de máscaras de fecha.

Date format localization

El MaskedDateField se adapta a los formatos de fecha regionales estableciendo la configuración de localización apropiada. Esto asegura que las fechas se muestren y analicen de una manera que coincida con las expectativas del usuario.

Región	Formato	Ejemplo
Estados Unidos	MM/DD/YYYY	`07/04/2023`
Europa	DD/MM/YYYY	`04/07/2023`
Estándar ISO	YYYY-MM-DD	`2023-07-04`

Para aplicar la localización, usa el método setLocale(). Acepta un java.util.Locale y ajusta automáticamente tanto el formato como el análisis:

dateField.setLocale(Locale.FRANCE);

Parsing logic

El MaskedDateField analiza la entrada del usuario en función de la máscara de fecha definida. Acepta tanto entradas numéricas completas como abbreviadas con o sin delimitadores, permitiendo una entrada flexible mientras asegura fechas válidas. El comportamiento de análisis depende del orden del formato definido por la máscara (por ejemplo, %Mz/%Dz/%Yz para mes/día/año). Este formato determina cómo se interpretan las secuencias numéricas.

Por ejemplo, asumiendo que hoy es 15 de septiembre de 2012, así es como se interpretarían varias entradas:

Example parsing scenarios

Entrada	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Un solo dígito siempre se interpreta como un número de día dentro del mes actual, por lo que esto sería el 1 de septiembre de 2012.	Igual que YMD	Igual que YMD
`12`	Dos dígitos siempre se interpretan como un número de día dentro del mes actual, por lo que esto sería el 12 de septiembre de 2012.	Igual que YMD	Igual que YMD
`112`	Tres dígitos se interpretan como un número de mes de 1 dígito seguido de un número de día de 2 dígitos, por lo que esto sería el 12 de enero de 2012.	Igual que YMD	Los tres dígitos se interpretan como un número de día de 1 dígito seguido de un número de mes de dos dígitos, por lo que esto sería el 1 de diciembre de 2012.
`1004`	Cuatro dígitos se interpretan como MMDD, por lo que esto sería el 4 de octubre de 2012.	Igual que YMD	Cuatro dígitos se interpretan como DDMM, por lo que esto sería el 10 de abril de 2012.
`020304`	Seis dígitos se interpretan como YYMMDD, por lo que esto sería el 4 de marzo de 2002.	Seis dígitos se interpretan como MMDDYY, por lo que esto sería el 3 de febrero de 2004.	Seis dígitos se interpretan como DDMMYY, por lo que esto sería el 2 de marzo de 2004.
`8 digits`	Ocho dígitos se interpretan como YYYYMMDD. Por ejemplo, `20040612` es el 12 de junio de 2004.	Ocho dígitos se interpretan como MMDDYYYY. Por ejemplo, `06122004` es el 12 de junio de 2004.	Ocho dígitos se interpretan como DDMMYYYY. Por ejemplo, `06122004` es el 6 de diciembre de 2004.
`12/6`	Dos números separados por cualquier delimitador válido se interpretan como MM/DD, por lo que esto sería el 6 de diciembre de 2012. Nota: Todos los caracteres excepto letras y dígitos son considerados delimitadores válidos.	Igual que YMD	Dos números separados por cualquier delimitador se interpretan como DD/MM, por lo que esto sería el 12 de junio de 2012.
`3/4/5`	5 de abril de 2012	4 de marzo de 2005	3 de abril de 2005

Setting min/max constraints

Puedes restringir el rango de fechas permitidas en un MaskedDateField utilizando los métodos setMin() y setMax():

dateField.setMin(LocalDate.of(2020, 1, 1));
dateField.setMax(LocalDate.of(2030, 12, 31));

Ambos métodos aceptan valores del tipo java.time.LocalDate. La entrada fuera del rango definido se considerará no válida.

Restoring the value

El MaskedDateField incluye una función de restauración que restablece el valor del campo a un estado predefinido u original. Esto es útil para revertir la entrada del usuario o restablecer a una fecha predeterminada.

dateField.setRestoreValue(LocalDate.of(2025, 1, 1));
dateField.restoreValue();

Ways to restore the value

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)

Puedes establecer el valor a restaurar con setRestoreValue(), pasando una instancia de LocalDate.

Mostrar Código

Java

Validation patterns

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

dateField.setPattern("^\\d{2}/\\d{2}/\\d{4}$");

Este patrón asegura que solo se consideren válidos los valores que coincidan con el formato MM/DD/YYYY (dos dígitos, barra, dos dígitos, barra, cuatro dígitos).

Formato de expresión regular

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

Notas sobre el manejo de entradas

El campo intenta analizar y formatear entradas de fecha numéricas en función de 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 inanalizable (por ejemplo, 99/99/9999), 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 la fecha esté correctamente formateada y sea significativa.

Date picker

El MaskedDateField incluye un selector de calendario incorporado que permite a los usuarios seleccionar una fecha de forma visual, en lugar de escribirla. Esto mejora la usabilidad para usuarios menos técnicos o cuando se requiere una entrada precisa.

Mostrar Código

Java

Accessing the picker

Puedes acceder al selector de fechas usando getPicker():

DatePicker picker = dateField.getPicker();

Show/hide the picker icon

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

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

Auto-open behavior

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 teclas de flecha):

picker.setAutoOpen(true);

Habilitar selección a través del selector

Para asegurarte de que los usuarios solo puedan seleccionar una fecha utilizando el calendario y no ingresarla manualmente, combina las siguientes dos configuraciones:

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

Esta configuración garantiza que toda la entrada de fecha 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.

Manually open the calendar

Para abrir el calendario programáticamente:

picker.open();

O usa el alias:

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

Show weeks in the calendar

El selector puede mostrar opcionalmente números de semanas en la vista del calendario:

picker.setShowWeeks(true);