Saltar al contenido principal

TextField

Abrir en ChatGPT
Sombra dwc-field 23.02
Java API

El componente TextField permite a los usuarios ingresar y editar texto en una sola línea. Puedes configurar el campo para mostrar un teclado virtual específico, como un teclado numérico, entrada de correo electrónico, entrada de teléfono o entrada de URL. El componente también proporciona validación incorporada para rechazar valores que no se ajusten al tipo especificado.

Usos​

Inheritance

This class is a Field component, and inherits its features and behaviors. For an overview of Field properties, events, and other important information, please refer to the Field documentation.

El TextField es adecuado para una amplia gama de escenarios donde se requiere entrada o edición de texto. Aquí hay algunos ejemplos de cuándo usar el TextField:

  1. Entradas de formularios: Un TextField se utiliza comúnmente en formularios para capturar la entrada del usuario, como nombres, direcciones o comentarios. Es mejor usar un TextField en una aplicación cuando la entrada es generalmente lo suficientemente corta como para caber en una línea.

  2. Funcionalidad de búsqueda: El TextField se puede usar para proporcionar una caja de búsqueda, permitiendo a los usuarios ingresar consultas de búsqueda.

  3. Edición de texto: Un TextField es ideal para aplicaciones que requieren edición de texto o creación de contenido, como editores de documentos, aplicaciones de chat o aplicaciones de toma de notas.

Tipos​

Puedes especificar el tipo del TextField utilizando el método setType(). De manera similar, puedes recuperar el tipo utilizando el método getType(), que devolverá un valor de enumeración.

  • Type.TEXT: Este es el tipo predeterminado para un TextField y elimina automáticamente los saltos de línea del valor de entrada.

  • Type.EMAIL: Este tipo es para ingresar direcciones de correo electrónico. Valida la entrada de acuerdo con la sintaxis estándar de correo electrónico. Además, proporciona a los navegadores y dispositivos compatibles un teclado dinámico que simplifica el proceso de escritura al incluir teclas de uso común como .com y @.

    nota

    Si bien esta validación confirma el formato de la dirección de correo electrónico, no garantiza que el correo electrónico exista.

  • Type.TEL: Este tipo se utiliza para ingresar un número de teléfono. El campo mostrará un teclado numérico en algunos dispositivos con teclados dinámicos.

  • Type.URL: Este tipo es para ingresar URLs. Valida si un usuario ingresa una URL que incluye un esquema y un nombre de dominio, por ejemplo: https://webforj.com. Además, proporciona a los navegadores y dispositivos compatibles un teclado dinámico que simplifica el proceso de escritura al incluir teclas de uso común como :, / y .com.

  • Type.SEARCH: Un campo de texto de una sola línea para ingresar cadenas de búsqueda. Los saltos de línea se eliminan automáticamente del valor de entrada.

Mostrar Código

Valor del campo​

El valor de un TextField representa la entrada actual del usuario como una cadena. En webforJ, esto se puede acceder utilizando el método getValue(), o actualizar programáticamente con setValue(String).

//Establecer el contenido inicial
textField.setValue("Contenido inicial");

//Recuperar el valor actual
String text = textField.getValue();

Si se utiliza el método getValue() en un campo sin un valor actual, devuelve una cadena vacía ("").

Este comportamiento es consistente con cómo el elemento HTML <input type="text"> expone su valor a través de JavaScript.

Combinar manejo de valores con validación

Aplica restricciones como un patrón, longitud mínima, o una longitud máxima para definir cuándo un valor se considera válido.

Texto de marcador de posición​

Puedes establecer un texto de marcador de posición para el TextField utilizando el método setPlaceholder(). El texto de marcador de posición se muestra cuando el campo está vacío, ayudando a inducir al usuario a ingresar una entrada apropiada en el TextField.

Texto seleccionado​

Es posible interactuar con la clase TextField para recuperar el texto seleccionado por el usuario y obtener información sobre la selección del usuario. Puedes recuperar el texto seleccionado en el TextField utilizando el método getSelectedText(). Este comportamiento comúnmente se utilizaría junto con un evento.

TextField textField = new TextField("Ingresa algo...");
Button getSelectionBtn = new Button("Obtener Texto Seleccionado");

getSelectionBtn.onClick(e -> {
  String selected = textField.getSelectedText();
  System.out.println("Texto seleccionado: " + selected);
});

De manera similar, es posible recuperar el rango de selección actual del TextField utilizando el método getSelectionRange(). Esto devuelve un objeto SelectionRange que representa los índices de inicio y fin del texto seleccionado.

Usando getSelectedText() vs carga útil del evento

Si bien puedes llamar a getSelectedText() manualmente dentro de un controlador de eventos, es más eficiente utilizar los datos de selección proporcionados en la carga útil del evento, como en un SelectionChangeEvent, para evitar búsquedas adicionales.

Coincidencia de patrones​

Puedes usar el método setPattern() para definir una regla de validación para el TextField utilizando una expresión regular. Establecer un patrón añade una validación de restricción que requiere que el valor de entrada coincida con el patrón especificado.

El patrón debe ser una expresión regular válida de JavaScript, tal como la interpreta el navegador. La bandera u (Unicode) se aplica internamente para asegurar una coincidencia precisa de puntos de código Unicode. No envuelvas el patrón en barras diagonales (/), ya que no son requeridas y se tratarán como caracteres literales.

textField.setPattern("[A-Za-z]{3}\\d{2}"); // por ejemplo ABC12

Si no se proporciona un patrón o la sintaxis es inválida, se ignora la regla de validación.

Ayuda contextual

Al utilizar patrones complejos para un TextField, considera usar una combinación de los métodos setLabel(), setHelperText(), y setTooltipText() para proporcionar pistas y orientación adicionales.

Longitud mínima y máxima​

El componente TextField admite validación de restricciones basada en el número de caracteres ingresados por el usuario. Esto se puede controlar utilizando los métodos setMinLength() y setMaxLength(). Utiliza ambos métodos para definir un límite claro de longitudes de entrada aceptables.

Requisitos de longitud

Por defecto, el campo muestra un mensaje cuando el valor de entrada está fuera de rango, indicando al usuario si necesita acortar o alargar su entrada. Este mensaje se puede sobrescribir con el método setInvalidMessage().

setMinLength()​

Este método establece el número mínimo de unidades de código UTF-16 que deben ingresarse para que el campo se considere válido. El valor debe ser un número entero y no debe exceder la longitud máxima configurada.

textField.setMinLength(5); // El usuario debe ingresar al menos 5 caracteres

Si la entrada contiene menos caracteres de los mínimos requeridos, la entrada fallará la validación de restricción. Esta regla solo se aplica cuando el usuario cambia el valor del campo.

setMaxLength()​

Este método establece el número máximo de unidades de código UTF-16 permitidas en el campo de texto. El valor debe ser 0 o mayor. Si no se establece, o se establece en un valor inválido, no se aplica un máximo.

textField.setMaxLength(20); // El usuario no puede ingresar más de 20 caracteres

El campo falla la validación de restricción si la longitud de entrada excede la longitud mínima. Al igual que con setMinLength(), esta validación solo se activa cuando el valor es cambiado por el usuario.

Mejores prácticas​

La siguiente sección describe algunas mejores prácticas sugeridas para la utilización del TextField.

  • Proporcionar etiquetas e instrucciones claras: Etiqueta el TextField claramente para indicar el tipo de información que los usuarios deben ingresar. Proporciona texto adicional de instrucción o valores de marcador de posición para guiar a los usuarios y establecer expectativas sobre la entrada requerida.

  • Corrección ortográfica y autocompletar: Cuando sea aplicable, considera utilizar la corrección ortográfica con setSpellCheck() y/o usar autocompletar en un TextField. Estas características pueden ayudar a los usuarios a ingresar información más rápido y reducir errores proporcionando valores sugeridos basados en entradas anteriores u opciones predefinidas.

  • Accesibilidad: Utiliza el componente TextField teniendo en mente la accesibilidad, cumpliendo con estándares de accesibilidad como etiquetado adecuado, soporte para navegación por teclado y compatibilidad con tecnologías asistivas. Asegúrate de que los usuarios con discapacidades puedan interactuar con el TextField de manera efectiva.