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.
La saisie numérique permet aux utilisateurs d'entrer ou de sélectionner des valeurs numériques dans une plage prédéterminée. Elle comprend des commandes permettant d'augmenter ou de diminuer la valeur de manière incrémentielle. Les utilisateurs peuvent également saisir des valeurs numériques directement dans le champ de saisie.
N’utilisez pas ce composant lorsqu’une valeur précise n’a pas d’importance pour l’utilisateur, mais qu’une fourchette suffit. Envisagez plutôt d'utiliser le composant curseur.
É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.
Valeur numérique : change lorsque l'utilisateur saisit une valeur dans le champ ou utilise les deux flèches à la fin de la saisie pour ajouter et soustraire des valeurs.
Champ de saisie numérique : conteneur, composé d'un remplissage et d'un trait, dans lequel l'utilisateur saisit des données.
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 numérique. 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 générique dans le champ de saisie numérique. 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 aucun texte générique au champ de saisie numérique.
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 numérique, les erreurs sont souvent liées à un élément qui doit être corrigé pour permettre une validation intégrée. Par exemple, si l'utilisateur ne remplit pas un champ obligatoire qui lui demande de fournir une estimation de son kilométrage annuel, vous pouvez utiliser un texte d'erreur pour le guider vers une solution : « Saisissez votre kilométrage annuel estimé ».
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 numérique apparaît sans valeur (par défaut), ni texte d'espace réservé ni saisie.
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 numérique 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 ».
Les utilisateurs peuvent activer la saisie numérique en cliquant dans la zone à l'intérieur du cadre. Une fois le focus appliqué, deux flèches apparaissent à l'extrémité de la zone de saisie. Ces commandes permettent aux utilisateurs d'augmenter ou de diminuer la valeur de manière incrémentielle.
Le nom accessible du composant de saisie numérique est issu d'un attribut aria-label. La modification de la valeur textuelle de l'élément de l'étiquette modifie également la valeur du nom accessible. L'attribut aria-required='true' par défaut prend la valeur « false » lorsque la case requise est cochée dans Storybook.
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.
The number of decimal places to display in the value. If it is set, the user is prevented from entering too many digits after the decimal point. If the value or initialValue props have too many digits after the decimal point, the displayed figure is rounded to the closest valid value.
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.
Initial value of the input. If the value prop is specified along with this prop, this prop's value is discarded. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Maximum value of the input. If this prop is passed, the component does not allow entering values higher than the specified value when using the Up Arrow key.
Minimum value of the input. If this prop is passed, the component does not allow entering values lower than the specified value when using the Down Arrow key.
Step increment for value changes. If this prop is passed, the component will increase or decrease its value by the specified step when the Up Arrow or Down Arrow keys are pressed.
Value of the input. Takes precedence over initialValue. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.
Vous pouvez utiliser des attributs de saisie HTML, à l'exception de tous ceux qui sont remplacés par Jutro. Ces attributs seront attribués à l'élément HTML input.
Notez que la plupart des attributs spécifiques à la saisie de numéro (step, min et max) sont inclus dans l'API du composant et peuvent avoir une logique spécifique à Jutro associée.
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.
Vous pouvez utiliser les états React pour contrôler la valeur d’une NumberInput, mais il existe certaines limites dans ce cas.
L’événement onChange n’est déclenché que si l’entrée est mise en évidence. Si la valeur est mise à jour en tant que composant contrôlé, le rappel onChange ne s’exécute pas.
Si la NumberInput a une propriété decimalPlaces et reçoit une valeur d’une mise à jour d’état React, la valeur affichée est arrondie à la valeur valide la plus proche.
Par exemple, dans le code ci-dessous, vous pouvez utiliser la première entrée pour modifier la valeur de la seconde entrée. Vous pouvez observer les deux comportements suivants lors de cette opération :
Si une valeur supérieure à 100 ou inférieure à 0 est saisie dans la première entrée, les messages de validation ne s’affichent pas dans la seconde entrée, car son rappel ne s’exécute pas.
Si plus de deux décimales sont saisies, la valeur affichée dans la deuxième entrée est arrondie à la valeur valide la plus proche.
exportfunctionNumberInputDecimalPlacesControlledExample(){ const[firstInputValue, setFirstInputValue]=useState(); const[secondInputValue, setSecondInputValue]=useState(); const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const handleFirstInputChange =useCallback((event, newValue)=>{ console.log(newValue) setFirstInputValue(newValue ||0); },[]); const handleSecondInputChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Number input" secondaryLabel="Change this value to see the second input update" onChange={handleFirstInputChange} /> <NumberInput label="Second number input" secondaryLabel="Value controlled by the first input" value={firstInputValue} decimalPlaces={2} onChange={handleSecondInputChange} stateMessages={validationMessages} min={min} max={max} readOnly /> ); }
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.
Un composant de saisie numérique de base a uniquement besoin de la propriété label pour être affiché. D'autres propriétés peuvent être utilisées pour compléter son comportement : placeholder, secondaryLabel, onChange ou les propriétés propres aux numéros.
<NumberInput label="Number input component" placeholder="Write what you want here" secondaryLabel="Free text input" />
Le composant de saisie numérique permet de configurer les valeurs maximale et minimale. Toutefois, cela n'est pas lié à une fonction de validation, mais au comportement du composant. Lors de la définition de l'une de ces deux propriétés, il n'est pas possible d'utiliser les flèches du composant pour définir une valeur inférieure à la propriété min ou une valeur supérieure à la propriété max.
<NumberInput label="Number input component with min and max" placeholder="Enter a value" secondaryLabel="Test the limits with using the arrows" min={20} max={40} />
Validation de la saisie d'un nombre lors d'une modification
Le composant de saisie numérique ne fournit pas de logique de validation spécifique, mais il permet d'inclure la validation du développeur et d'utiliser 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é.
exportfunctionNumberInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const max =100; const min =0; const onChange =useCallback((e, newValue)=>{ setValidationMessages({}); if(newValue &&(newValue > max || newValue < min)){ setValidationMessages({ error:['Value must be between 0 and 100'], }); } },[]); return( <NumberInput label="Enter value" secondaryLabel="Min = 0. Max = 100" stateMessages={validationMessages} min={min} max={max} onChange={onChange} /> ); }
La propriété decimalPlaces spécifie le nombre de décimales à afficher. Elle empêche les utilisateurs de saisir un trop grand nombre de chiffres après la virgule, mais si les propriétés initialValue ou value sont définies, le nombre est arrondi à la valeur valide la plus proche.
Par exemple, si decimalPlaces est défini sur 2 , l’utilisateur ne peut pas saisir plus de deux décimales. Toutefois, les propriétés initialValue ou value peuvent comporter trois décimales ou plus.
<NumberInput label="Number input component limited decimals" placeholder="Enter a value" secondaryLabel="Try to add an additional decimal" decimalPlaces={2} /> <NumberInput label="Number input with initial value" secondaryLabel="Rounded up from 5.666" initialValue={5.666} decimalPlaces={2} readOnly /> <NumberInput label="Number input with value" secondaryLabel="Rounded up from 5.666" value={5.666} decimalPlaces={2} readOnly />
Le comportement de la propriété decimalPlaces a été modifié. L’utilisateur ne peut désormais pas saisir de chiffres supplémentaires au-delà de la limite decimalPlaces. Par exemple, si decimalPlaces est 2, l’utilisateur ne peut pas saisir un troisième chiffre après la virgule.
Les propriétés initialValue ou value peuvent comporter des chiffres supplémentaires après la virgule, mais la valeur affichée est arrondie à la valeur valide la plus proche.
Un nouveau composant @jutro/components/NumberInput a été introduit pour remplacer InputNumberField.
Le précédent composant lié à la valeur numérique InputNumberField est obsolète et a été déplacé vers le package @jutro/legacy. Pour afficher la documentation correspondante, passez à une version antérieure.
