MaskedTextField

El componente MaskedTextField proporciona una entrada de texto configurable que exige reglas de formato y validación. Es adecuado para aplicaciones que requieren entradas estructuradas, como sistemas financieros, de comercio electrónico y de atención médica.

Básicos

El MaskedTextField se puede instanciar con o sin parámetros. Puedes definir un valor inicial, una etiqueta, un texto de marcador de posición y un oyente en caso de que el valor cambie.

MaskedTextField field = new MaskedTextField("ID de Cuenta");
field.setMask("ZZZZ-0000")
  .setHelperText("Máscara: ZZZZ-0000 - por ejemplo: SAVE-2025")

Reglas de máscara

El MaskedTextField formatea la entrada de texto utilizando una máscara, que es una cadena que define qué caracteres son permitidos en cada posición. Esto asegura una entrada consistente y estructurada para cosas como números de teléfono, códigos postales y formatos de identificación.

Aplicando máscaras programáticamente

Para formatear cadenas con la misma sintaxis de máscara fuera de un campo, por ejemplo, al renderizar datos en una Table, utiliza la clase utilitaria MaskDecorator.

Caracteres de máscara soportados

Carácter	Descripción
`X`	Cualquier carácter imprimible
`a`	Cualquier carácter alfabético (mayúscula o minúscula)
`A`	Cualquier carácter alfabético; las letras minúsculas se convierten a mayúsculas
`0`	Cualquier dígito (0–9)
`z`	Cualquier dígito o letra (mayúscula o minúscula)
`Z`	Cualquier dígito o letra; las letras minúsculas se convierten a mayúsculas

Todos los demás caracteres en la máscara se tratan como literales y deben ser escritos exactamente. Por ejemplo, una máscara como XX@XX requiere que el usuario ingrese un @ en el medio.

Los caracteres inválidos se ignoran silenciosamente.
La entrada corta se completa con espacios.
La entrada larga se trunca para ajustarse a la máscara.

Ejemplos

field.setMask("(000) 000-0000");     // Ejemplo: (123) 456-7890
field.setMask("A00 000");            // Ejemplo: A1B 2C3 (código postal canadiense)
field.setMask("ZZZZ-0000");          // Ejemplo: ABCD-1234
field.setMask("0000-0000-0000-0000");// Ejemplo: 1234-5678-9012-3456

Entrada completa permitida

Si la máscara solo contiene X, el campo se comporta como un TextField estándar, permitiendo cualquier entrada imprimible. Esto es útil cuando deseas reservar la capacidad de formatear sin aplicar reglas de caracteres estrictas.

Mostrar Código

MaskedTextFieldView.java

Patrones de validación

Mientras que las máscaras definen la estructura de la entrada, puedes combinarlas con patrones de validación para imponer reglas de entrada más específicas. Esto añade una capa adicional de validación del lado del cliente utilizando expresiones regulares.

Utiliza el método setPattern() para aplicar una expresión regular personalizada:

field.setPattern("[A-Za-z0-9]{10}"); // Impone un código alfanumérico de 10 caracteres

Esto asegura que la entrada no solo coincida con la máscara, sino que también se ajuste a una estructura definida, como longitud o caracteres permitidos.

Esto es especialmente útil cuando:

La máscara permite demasiada flexibilidad
Deseas imponer una longitud exacta o un formato específico (por ejemplo, hex, Base64, UUID)

Formato de expresión regular

El patrón debe ser una expresión regular válida de JavaScript, como la que utiliza el tipo RegExp. Puedes encontrar más detalles en la documentación del atributo pattern de HTML.

Restaurando el valor

El MaskedTextField 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 del usuario o revertir a una entrada por defecto.

field.setRestoreValue("ABC123");
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 sea reemplazada por un oyente de eventos)

Puedes establecer el valor a restaurar con setRestoreValue(). Si no se establece un valor de restauración, el campo volverá al valor inicial en el momento en que se renderizó.

Mostrar Código

MaskedTextFieldRestoreView.java