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 email, entrada telefónica o entrada de URL. El componente también proporciona validación incorporada para rechazar valores que no cumplen con el 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 utilizar un TextField en una aplicación cuando la entrada es lo suficientemente corta como para caber en una línea.

2. Funcionalidad de búsqueda: El TextField se puede utilizar para proporcionar un cuadro 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 de TextField utilizando el método setType(). De manera similar, puedes recuperar el tipo utilizando el método getType(), que devolverá un valor enum.

• 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 del 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 comúnmente utilizadas 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 telefónico 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 comúnmente utilizadas 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

TextFieldView.java

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 actualizarse 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.

Combina el manejo del valor con la 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 del marcador de posición se muestra cuando el campo está vacío, ayudando a incitar al usuario a ingresar información adecuada 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 se utilizaría comúnmente en conjunto 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 utilizar el método setPattern() para definir una regla de validación para el TextField usando 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 garantizar una coincidencia precisa de los puntos de código Unicode. No envuelvas el patrón en barras inclinadas (/), ya que no son necesarias 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, la regla de validación se ignora.

Ayuda contextual

Cuando utilices 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 claro límite 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 que el mínimo requerido, la entrada fallará la validación de restricciones. 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 ningún máximo.

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

El campo falla la validación de restricciones si la longitud de la 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 prácticas recomendadas sugeridas para la utilización del TextField.

• Proporcionar etiquetas e instrucciones claras: Etiqueta el TextField de manera clara 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 para la entrada requerida.

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

• Accesibilidad: Utiliza el componente TextField teniendo en cuenta la accesibilidad, adhiriéndote a estándares de accesibilidad tales 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.