Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.0.x pour consulter cette documentation.
Le composant de saisie de texte permet aux utilisateurs d'entrer du texte et des nombres dans les champs de saisie de données. Les saisies de texte font partie des composants d'interface les plus importants et les plus utilisés avec lesquels les utilisateurs interagissent. Ils permettent aux utilisateurs de fournir les informations nécessaires à l'exécution d'une tâche spécifique ou d'un ensemble de tâches.
Lorsque l'utilisateur a besoin de rechercher quelque chose. Utilisez plutôt le composant de recherche.
Si l'utilisateur peut uniquement saisir une option à partir d'une liste prédéfinie. Envisagez l'utilisation d'un contrôle de sélection tel que la liste déroulante ou le groupe de cases d'option.
Étiquette : décrit l'objectif d'un champ de saisie.
Texte d'aide (facultatif) : fournit un contexte supplémentaire, des conseils ou des informations utiles pour aider l'utilisateur. Souvent utilisé pour expliquer des exigences spécifiques permettant de remplir correctement un champ.
Champ de saisie de texte : le conteneur du champ de texte, composé d'un remplissage et d'un trait, dans lequel les utilisateurs saisissent du texte.
Mettez une majuscule en début de phrase pour tous les aspects relatifs à la conception des interfaces de produit Guidewire. Ne mettez pas la 1re lettre du 1er mot du titre en majuscule.
Utilisez des verbes au présent et la forme active dans la plupart des cas.
Placez une étiquette claire et visible en dehors du champ de saisie de texte. Un champ de saisie sans étiquette est ambigu et ne permet pas l'accessibilité.
Placez une étiquette permanente en dehors du champ.
Ne supposez pas que le champ est explicite sans étiquette.
Utilisez le texte d'aide pour fournir des informations sur les éléments à saisir et la façon de le faire. Voici quelques exemples de ce que vous pouvez inclure dans le texte d'aide :
Contexte pour aider l'utilisateur, par exemple la façon dont les informations seront utilisées
Conseils sur le type d'informations contenues dans le champ de saisie
Exemples de formatage ou exigences
N'utilisez le texte d'aide que pour les informations pertinentes. Évitez d'utiliser un texte d'aide qui reformule simplement les mêmes informations que celles qui apparaissent dans l'étiquette.
Mettez la première lettre de la phrase en majuscule pour le texte d'aide. Rédigez le texte d'aide sous la forme de 1 ou 2 phrases courtes et complètes se terminant par un point. Lorsque vous affichez des exemples de mise en forme, vous n'avez pas besoin de mettre un point final.
Utilisez le texte d'aide pour fournir une aide ou un contexte supplémentaire à l'utilisateur.
N'utilisez pas le texte d'aide pour simplement reformuler les mêmes informations que celles qui apparaissent dans l'étiquette.
Ne mettez pas de texte d'espace réservé dans le champ de saisie de texte. Un texte d'espace réservé sollicite la mémoire à court terme des utilisateurs, car il disparaît une fois qu'une valeur est entrée. Il représente également un fardeau supplémentaire pour les utilisateurs souffrant de troubles visuels et cognitifs.
Placez donc plutôt les conseils et les instructions, y compris les exemples de formatage et les exigences, en dehors du champ.
Placez les conseils et les instructions, y compris les exemples de formatage et les exigences, en dehors du champ.
N'ajoutez pas d'espaces réservés au champ de saisie de texte.
Utiliser un texte d'erreur pour guider les utilisateurs
Le texte du message d'erreur indique à l'utilisateur comment corriger l'erreur. Dans le cas du champ de saisie de texte, les erreurs sont souvent liées à quelque chose qui doit être corrigé pour la validation en ligne. Par exemple, si l'utilisateur ne remplit pas un champ obligatoire qui demande son adresse e-mail, vous pouvez utiliser un texte d'erreur pour le guider vers une solution : « Entrez votre adresse e-mail ».
Mettez la 1re lettre du 1er mot en majuscule pour le texte d'erreur. Rédigez 1 à 2 phrases courtes et complètes qui se terminent par un point.
Utilisez le texte d'erreur pour guider l'utilisateur et lui proposer une solution.
Ne rédigez pas de messages d'erreur ambigus ou ne laissez pas les utilisateurs deviner comment résoudre un problème.
Utilisez un astérisque (*) pour indiquer les champs obligatoires. L'astérisque précède l'étiquette du champ. Cela permet aux utilisateurs de localiser facilement les champs devant obligatoirement être renseignés en regardant uniquement le caractère le plus à gauche de l'étiquette.
En plus de marquer les champs obligatoires par un astérisque, il est recommandé d'inclure des instructions claires en haut du formulaire, telles que « Tous les champs marqués d'un astérisque sont obligatoires », afin de vous assurer que les utilisateurs comprennent la signification de l'astérisque.
Utilisez un astérisque pour signaler qu'un champ est obligatoire.
N'utilisez pas d'astérisque pour signaler quelque chose qui est facultatif.
Le champ de saisie de texte apparaît sans valeur (par défaut), sans texte d'espace réservé ou sans entrée renseignée.
Visuel
État
Description
Aucune valeur (par défaut)
Indique à l'utilisateur qu'aucune valeur n'a été sélectionnée et qu'il n'y a pas d'espace réservé.
Espace réservé
Indique à l'utilisateur qu'aucune valeur n'a été saisie. L'espace réservé est grisé.
Entrée renseignée
Indique à l'utilisateur que l'entrée est renseignée.
Les champs de saisie de texte ont également des états interactifs : Activé, Focus, Désactivé, Erreur, Lecture seule et Affichage uniquement.
État
Description
Activé
Indique à l'utilisateur que l'élément est prêt à interagir.
Focus
Indique à l'utilisateur l'élément de l'interface utilisateur sur lequel le système est centré.
Désactivé
Indique à l'utilisateur que la valeur de saisie ne peut pas être modifiée en raison de facteurs locaux. Par exemple, une case à cocher située au-dessus du champ de saisie doit être cochée pour accéder à ce champ de saisie. Un utilisateur peut effectuer une action pour l'activer en interagissant avec la page.
Erreur
Indique que l'utilisateur a commis une erreur de validation. Le texte d'erreur permet aux utilisateurs d'apporter une correction.
Lecture seule
Indique à l'utilisateur que la valeur de saisie ne peut pas être modifiée en raison de facteurs externes. Par exemple, pas d'accès en écriture. Un utilisateur peut effectuer une action pour l'activer, par exemple en contactant un administrateur.
Affichage uniquement
L'état Affichage uniquement est utilisé dans deux cas :
Un élément d'interface utilisateur est utilisé en mode affichage.
Un élément d'interface utilisateur est affiché en mode édition, mais il n'est jamais modifiable.
Cet état était auparavant appelé « lecture seule ».
L'étiquette et la saisie sont associées l'une à l'autre par programmation. Par défaut, une infobulle est positionnée à côté de l'étiquette. Elle inclut l'attribut WAI-ARIA de aria-label="Show tooltip", et également aria-expanded="false" qui bascule sur « true » lorsque l'infobulle est déclenchée. Le contenu de l'infobulle est lu par les lecteurs d'écran au moyen du rôle WAI-ARIA « alert ». Lorsque la case obligatoire est cochée dans Storybook, l'attribut « obligatoire » est ajouté au balisage et la valeur aria-required passe de « true » à « false ».
Si le contenu du texte saisi déborde, l'utilisateur doit pouvoir faire défiler le contenu horizontalement d'un bout à l'autre à l'aide de la commande Shift+Scroll. L'utilisateur peut également utiliser Left Arrow et Right Arrow pour déplacer le curseur d'un côté à l'autre.
Ce composant a été validé pour répondre aux directives d’accessibilité WCAG 2.2 AA dans sa configuration de base par défaut. Il s’agit notamment de s’assurer que :
Le rapport de contraste des éléments textuels par rapport à leur arrière-plan est supérieur à 4.5:1.
Le contenu non textuel qui doit transmettre le sens (comme les icônes et les indicateurs de focus) a un rapport de contraste d’au moins 3:1 avec ses couleurs adjacentes.
Cet élément peut être utilisé à l’aide d’un clavier et d’une souris.
Le contenu est accessible à l’aide de lecteurs d’écran, tels que JAWS et VoiceOver.
La conformité de l’accessibilité dépend en définitive de la façon dont ce composant est implémenté et personnalisé. Les modifications apportées par l’auteur du contenu peuvent affecter l’accessibilité. Pour en savoir plus sur notre modèle de responsabilité partagée, consultez notre Déclaration d’accessibilité Jutro complète.
Lorsque vous utilisez ce composant dans votre application, assurez-vous que les étiquettes et les instructions sont pertinentes et concises. Fournissez des instructions supplémentaires si nécessaire.
Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.0.x pour consulter cette documentation.
Assurez-vous de comprendre la surface de l'API des composants du système de conception, ainsi que les implications et les compromis. Pour en savoir plus, reportez-vous à notre introduction à l'API des composants.
If set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
Value of input. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.
Le résultat de la transmission de ces propriétés id et maxLength est qu'elle fera partie de l'élément HTML input créé dans le DOM HTML. Dans le cas de maxLength, elle empêche l'utilisateur d'écrire une valeur supérieure à 10 caractères. Cela ne peut être fait qu'en collant directement la valeur.
Les entrées Jutro ont implémenté des gestionnaires impératifs en tant que mécanisme permettant d'accéder à certaines fonctionnalités natives communes susceptibles de vous être utiles. Les fonctionnalités suivantes sont disponibles :
Définir le focus pour vous permettre de définir le focus utilisateur dans un composant spécifique
Flou pour supprimer le focus du composant
Faire défiler l'écran jusqu'au composant pour pouvoir amener l'utilisateur à une zone spécifique de la page.
Ces fonctionnalités sont fournies via la propriété ref, qui les expose comme suit :
Bien que certains composants de Jutro puissent fournir des fonctionnalités complémentaires ou une fonction d'aide pour faciliter le processus de validation, il vous appartient, en tant que développeur, de gérer la validation de toute entrée utilisateur (en utilisant ou non les fonctions d'aide complémentaires) et de déterminer les messages d'erreur à afficher.
Le comportement des composants Jutro est basé sur l'implémentation du développeur.
Quand est-ce que des messages d'erreur s'affichent ?
Les messages d'erreur ne s'affichent que lorsque vous les transmettez au composant via la propriété stateMessages. Cette propriété reçoit un objet avec le contenu suivant :
Le composant affiche chaque message d'erreur fourni dans le même ordre que dans la série.
Quand la validation a-t-elle lieu ?
Cette décision vous revient en tant que développeur. Étant donné que les composants ne déterminent pas le moment où la validation est effectuée ou le moment où l'erreur doit être affichée, vous devez implémenter la logique pour la traiter en fonction des exigences du projet, par exemple lorsque l'utilisateur modifie le contenu, lorsque le composant active une autre fenêtre et lors de la soumission du formulaire.
Note: Il existe des versions obsolètes de ce composant. Passez à une version de la documentation antérieure à la version 10.0.x pour consulter cette documentation.
Le composant TextInput a uniquement besoin que la propriété label soit affichée. D'autres propriétés telles que placeholder, secondaryLabel et onChange peuvent être utilisées pour compléter son comportement.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
TextInput, ainsi que les autres entrées, offrent toutes la possibilité de définir le composant en tant que display only. Lorsque cette propriété displayOnly est définie sur true, le composant s'affiche alors sous forme de texte, sans l'apparence et la convivialité spécifiques de la saisie.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" value="this is the value" displayOnly={true} />
La propriété tooltip fait en sorte que le composant affiche l'icône d'infobulle. Lorsque l'utilisateur interagit avec lui, il affiche également des informations complémentaires. Cette propriété peut recevoir du texte à afficher {text: "this will be displayed when tooltip is opened"}. Vous pouvez également déterminer quelle action spécifique fait apparaître l'infobulle en transmettant un deuxième attribut trigger. Cette méthode accepte les événements HTML standard tels que pointerover, focus et blur. Par défaut, l'infobulle s'ouvre en cliquant sur l'icône d'infobulle.
Dans cet exemple, l'infobulle s'affiche lorsque la souris se trouve sur l'icône d'infobulle.
<TextInput label="Text input component" placeholder="Write what you want here" secondaryLabel="Free text input" tooltip={{text:'tooltip text',trigger:'pointerover'}} />
Validation de la saisie de texte lors d'une modification
Le composant TextInput ne fournit pas de logique de validation spécifique, mais il fournit une méthode pour inclure la validation du développeur et utilise la propriété stateMessages pour afficher tout message d'erreur requis.
Il s'agit d'un exemple de traitement de la validation lorsque l'événement onChange est déclenché.
functionTextInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue)=>{ if(!newValue || newValue.indexOf('a')==-1){ setValidationMessages({}); }else{ setValidationMessages({ error:['The text cannot contain `a` character'], }); } },[]); return( <TextInput label="Do not accept words with 'a'" secondaryLabel="Will raise an error if contains 'a' character" stateMessages={validationMessages} onChange={onChange} /> ); }
La propriété value peut être utilisée pour le scénario de composant contrôlé :
exportfunctionInputControlled(){ const[updatedValue, setNewValue]=useState('first given value'); constonChange=(e, newValue)=>{ setNewValue(newValue); }; return( <div> <TextInput label="Enter here the value to be assigned input below" onChange={onChange} /> <br/> <TextInput label="Changes with the above" secondaryLabel="This cannot be manually modified" value={updatedValue} /> </div> ); }
TextInput, et certaines autres entrées, permettent toutes l'utilisation d'une propriété ref pour accéder à certains comportements natifs. Toutefois, seules certaines fonctionnalités sont exposées. Dans ce cas, lorsque l'utilisateur clique sur le bouton, le focus est automatiquement défini dans l'entrée suivante :
exportfunctionInputRef(){ const inputRef =useRef(null); constsetFocus=(e)=>{ inputRef?.current?.focus(); }; return( <div> <Button label="Set focus on text input" onClick={setFocus}></Button> <TextInput label="Get the focus from the button" ref={inputRef} /> </div> ); }
Le nouveau composant @jutro/components/TextInput a été introduit et remplace InputField.
Le composant précédent InputField est obsolète et a été déplacé vers le package @jutro/legacy. Pour afficher la documentation correspondante, passez à une version de la documentation antérieure à la version 10.0.
Composant
Ancien emplacement
Nouvel emplacement
InputField
@jutro/components/InputField
@jutro/legacy/components/InputField
Des codemods sont disponibles afin de renommer automatiquement les importations existantes.
