Passer au contenu principal

TextField

Ouvrir dans ChatGPT
Ombre dwc-field 23.02
Java API

Le composant TextField permet aux utilisateurs d'entrer et d'éditer du texte sur une seule ligne. Vous pouvez configurer le champ pour afficher un clavier virtuel spécifique, tel qu'un pavé numérique, une saisie d'email, une saisie de numéro de téléphone ou une saisie d'URL. Le composant fournit également une validation intégrée pour rejeter les valeurs qui ne respectent pas le type spécifié.

Usages​

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.

Le TextField convient à un large éventail de scénarios où une saisie ou une édition de texte est requise. Voici quelques exemples de quand utiliser le TextField :

  1. Saisies de formulaire : Un TextField est couramment utilisé dans les formulaires pour capturer les saisies des utilisateurs, telles que les noms, adresses ou commentaires. Il est préférable d'utiliser un TextField dans une application lorsque la saisie est généralement suffisamment courte pour tenir sur une seule ligne.

  2. Fonctionnalité de recherche : Le TextField peut être utilisé pour fournir une boîte de recherche, permettant aux utilisateurs de saisir des requêtes de recherche.

  3. Édition de texte : Un TextField est idéal pour les applications qui nécessitent l'édition de texte ou la création de contenu, comme les éditeurs de documents, les applications de chat, ou les applications de prise de notes.

Types​

Vous pouvez spécifier le type du TextField en utilisant la méthode setType(). De même, vous pouvez récupérer le type en utilisant la méthode getType(), qui renverra une valeur énumérée.

  • Type.TEXT : Il s'agit du type par défaut pour un TextField et il supprime automatiquement les sauts de ligne de la valeur d'entrée.

  • Type.EMAIL : Ce type est utilisé pour entrer des adresses e-mail. Il valide l'entrée selon la syntaxe e-mail standard. De plus, il fournit aux navigateurs et dispositifs compatibles un clavier dynamique qui simplifie le processus de saisie en incluant des touches couramment utilisées telles que .com et @.

    remarque

    Bien que cette validation confirme le format de l'adresse e-mail, elle ne garantit pas que l'e-mail existe.

  • Type.TEL : Ce type est utilisé pour entrer un numéro de téléphone. Le champ affichera un clavier téléphonique sur certains dispositifs avec claviers dynamiques.

  • Type.URL : Ce type est utilisé pour entrer des URL. Il valide si un utilisateur entre une URL qui inclut un schéma et un nom de domaine, par exemple : https://webforj.com. De plus, il fournit aux navigateurs et dispositifs compatibles un clavier dynamique qui simplifie le processus de saisie en incluant des touches couramment utilisées comme :, /, et .com.

  • Type.SEARCH : Un champ de texte à une ligne pour entrer des chaînes de recherche. Les sauts de ligne sont automatiquement supprimés de la valeur d'entrée.

Afficher le code

Valeur du champ​

La valeur d'un TextField représente la saisie actuelle de l'utilisateur sous forme de chaîne. Dans webforJ, cela peut être accédé en utilisant la méthode getValue(), ou mis à jour programmatique avec setValue(String).

// Définir le contenu initial
textField.setValue("Contenu initial");

// Récupérer la valeur actuelle
String text = textField.getValue();

Si la méthode getValue() est utilisée sur un champ sans valeur actuelle, elle renvoie une chaîne vide ("").

Ce comportement est conforme à la manière dont l'élément HTML <input type="text"> expose sa valeur via JavaScript.

Combinez la gestion des valeurs avec la validation

Appliquez des contraintes telles qu'un pattern, une longueur minimale, ou une longueur maximale pour définir quand une valeur est considérée comme valide.

Texte d'espace réservé​

Vous pouvez définir un texte d'espace réservé pour le TextField en utilisant la méthode setPlaceholder(). Le texte d'espace réservé est affiché lorsque le champ est vide, aidant à inciter l'utilisateur à entrer une saisie appropriée dans le TextField.

Texte sélectionné​

Il est possible d'interagir avec la classe TextField pour récupérer le texte sélectionné par un utilisateur et obtenir des informations sur la sélection de l'utilisateur. Vous pouvez récupérer le texte sélectionné dans le TextField en utilisant la méthode getSelectedText(). Ce comportement serait couramment utilisé en conjonction avec un événement.

TextField textField = new TextField("Entrez quelque chose...");
Button getSelectionBtn = new Button("Obtenir le texte sélectionné");

getSelectionBtn.onClick(e -> {
  String selected = textField.getSelectedText();
  System.out.println("Texte sélectionné : " + selected);
});

De même, il est possible de récupérer la plage de sélection actuelle du TextField en utilisant la méthode getSelectionRange(). Cela renvoie un objet SelectionRange représentant les indices de début et de fin du texte sélectionné.

Utilisation de getSelectedText() vs charge utile d'événement

Bien que vous puissiez appeler getSelectedText() manuellement à l'intérieur d'un gestionnaire d'événements, il est plus efficace d'utiliser les données de sélection fournies dans la charge utile de l'événement—comme dans un SelectionChangeEvent—pour éviter des recherches supplémentaires.

Correspondance de motifs​

Vous pouvez utiliser la méthode setPattern() pour définir une règle de validation pour le TextField en utilisant une expression régulière. La définition d'un motif ajoute une validation de contrainte qui exige que la valeur d'entrée corresponde au motif spécifié.

Le motif doit être une expression régulière JavaScript valide, telle qu'interprétée par le navigateur. Le drapeau u (Unicode) est appliqué en interne pour assurer un appariement exact des points de code Unicode. Ne pas entourer le motif de barres obliques (/), car elles ne sont pas nécessaires et seront considérées comme des caractères littéraux.

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

Si aucun motif n'est fourni, ou si la syntaxe est invalide, la règle de validation est ignorée.

Aide contextuelle

Lorsque vous utilisez des motifs complexes pour un TextField, envisagez d'utiliser une combinaison des méthodes setLabel(), setHelperText(), et setTooltipText() pour fournir des indications et des conseils supplémentaires.

Longueur minimale et maximale​

Le composant TextField prend en charge la validation des contraintes basée sur le nombre de caractères saisis par l'utilisateur. Cela peut être contrôlé en utilisant les méthodes setMinLength() et setMaxLength(). Utilisez les deux méthodes pour définir une limite claire des longueurs d'entrée acceptables.

Exigences de longueur

Par défaut, le champ affiche un message lorsque la valeur d'entrée est hors de portée, indiquant à l'utilisateur s'il doit raccourcir ou allonger sa saisie. Ce message peut être remplacé par la méthode setInvalidMessage().

setMinLength()​

Cette méthode définit le nombre minimum d'unités de code UTF-16 qui doivent être saisies pour que le champ soit considéré comme valide. La valeur doit être un nombre entier et ne doit pas dépasser la longueur maximale configurée.

textField.setMinLength(5); // L'utilisateur doit saisir au moins 5 caractères

Si l'entrée contient moins de caractères que le minimum requis, l'entrée échouera à la validation des contraintes. Cette règle ne s'applique que lorsque l'utilisateur change la valeur du champ.

setMaxLength()​

Cette méthode définit le nombre maximum d'unités de code UTF-16 autorisées dans le champ de texte. La valeur doit être 0 ou supérieure. Si elle n'est pas définie, ou définie sur une valeur invalide, aucune limite maximale n'est appliquée.

textField.setMaxLength(20); // L'utilisateur ne peut pas saisir plus de 20 caractères

Le champ échoue à la validation des contraintes si la longueur d'entrée dépasse la longueur minimale. Comme avec setMinLength(), cette validation est uniquement déclenchée lorsque la valeur est changée par l'utilisateur.

Meilleures pratiques​

La section suivante décrit quelques meilleures pratiques suggérées pour l'utilisation du TextField.

  • Fournir des étiquettes et des instructions claires : Étiquetez le TextField clairement pour indiquer le type d'information que les utilisateurs doivent saisir. Fournissez des textes d'instruction ou des valeurs d'espace réservé supplémentaires pour guider les utilisateurs et définir les attentes concernant l'entrée requise.

  • Vérification orthographique et auto-complétion : Lorsque cela est applicable, envisagez d'utiliser la vérification orthographique avec setSpellCheck() et/ou d'utiliser l'auto-complétion dans un TextField. Ces fonctionnalités peuvent aider les utilisateurs à saisir des informations plus rapidement et à réduire les erreurs en fournissant des valeurs suggérées basées sur des saisies précédentes ou des options prédéfinies.

  • Accessibilité : Utilisez le composant TextField en gardant à l'esprit l'accessibilité, en respectant les normes d'accessibilité telles que l'étiquetage approprié, le support de la navigation au clavier et la compatibilité avec les technologies d'assistance. Assurez-vous que les utilisateurs ayant des handicaps peuvent interagir efficacement avec le TextField.