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.
Les cases à cocher permettent aux utilisateurs d'effectuer une sélection dans une liste d'éléments. Elles apparaissent souvent dans des formulaires dans lesquels la collecte d'informations utilisateur n'est pas nécessaire. Lors de l'utilisation de cases à cocher, les utilisateurs peuvent sélectionner un ou plusieurs éléments d'un ensemble.
Pour savoir quand utiliser ce composant en détail, consultez l'arbre de décision des composants de l'interface utilisateur suivant :
Lorsqu'une action doit être appliquée instantanément. Utilisez le composant switch à la place.
Si un utilisateur peut sélectionner une seule option dans une liste. Utilisez le composant de ](./radio-group.mdx)groupe de cases d'option[ à la place.
Lorsqu'il y a 6 options ou plus parmi lesquelles les utilisateurs peuvent choisir. Utilisez plutôt le composant Élément déroulant.
Un groupe de cases à cocher est une liste d'éléments accompagnés d'une case à cocher sous une étiquette de groupe. Les utilisateurs peuvent sélectionner tous les éléments pertinents sous l'étiquette du groupe. Ce format est utile en présence de plusieurs options valides pour un cas unique.
Jutro prend également en charge les cases à cocher accompagnant un élément unique. Notez que les cases à cocher peuvent être utilisées pour activer ou désactiver une option (par exemple, lors de l'activation ou de la désactivation d'un paramètre).
Groupe de cases à cocher (gauche) et case à cocher unique (droite).
La case à cocher est constituée des éléments suivants :
Étiquette du groupe de cases à cocher : explique l'objectif d'un groupe de cases à cocher.
Texte d'aide (facultatif) : donne un contexte supplémentaire pour le groupe de cases à cocher.
Entrée Case à cocher : indique l'état approprié. Par d éfaut, cette option n'est pas sélectionnée.
Étiquette de la case à cocher : décrit les informations qui seront sélectionnées ou désélectionnées.
Icône d'infobulle (facultatif) : permet de lever toute ambiguïté sur le contexte d'une case à cocher donnée. L'infobulle apparaît lorsque vous la survolez.
Un groupe de cases à cocher peut être organisé verticalement ou horizontalement en fonction de la structure de la page. Par défaut, les cases à cocher sont disposées verticalement pour faciliter la lecture.
Comme c'est le cas pour tous les composants de saisie, l'étiquette du groupe de cases à cocher peut apparaître en haut (par défaut) ou à gauche de l'entrée elle-même.
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.
Les groupes de cases à cocher doivent avoir une étiquette qui décrit ce que représente la liste d'options. Un groupe de cases à cocher sans étiquette est ambigu et inaccessible.
Utilisez l'étiquette du groupe pour indiquer la catégorie du regroupement ou décrire les actions à effectuer en dessous.
Incluez une étiquette qui décrit clairement ce que représente la liste d'options.
Ne supposez pas que les options sont explicites sans étiquette.
Utilisez des étiquettes de case à cocher claires et cohérentes
Essayez de faire en sorte que toutes les étiquettes d'un groupe de cases à cocher soient aussi parallèles que possible. Elles doivent avoir le même format et être à peu près de la même longueur.
Utilisez des étiquettes claires, concises et sans ambiguïté. Les étiquettes doivent décrire des options facilement compréhensibles pour un utilisateur moyen.
Utilisez une formulation positive et active pour les étiquettes des cases à cocher. Indiquez clairement ce qui se passera si l'utilisateur coche une case particulière et ce qui se passera s'il la laisse décochée.
Évitez les négations telles que « Ne m'envoyez pas de notifications par e-mail ». Cela signifierait que l'utilisateur devrait cocher la case pour que quelque chose ne se produise pas.
Lorsque vous demandez le consentement de l'utilisateur, utilisez la première personne. Par exemple, « J'accepte les conditions d'utilisation ».
Utilisez des phrases parallèles et essayez de garder à peu près la même longueur pour toutes les étiquettes.
N'utilisez pas de formulations très variées. Cela peut ralentir ou même dérouter les utilisateurs.
Utilisez des étiquettes concises pour les cases à cocher
Limitez les étiquettes de texte des cases à cocher à une seule ligne. Nous vous recommandons d'utiliser un à trois mots pour les étiquettes des cases à cocher.
Ne tronquez pas les étiquettes de case à cocher avec des points de suspension (...). Si le texte de l'étiquette est trop long pour l'espace horizontal disponible, envisagez de le reformuler. Si les étiquettes de case à cocher sont trop longues, vous pouvez également renvoyer le texte sur une deuxième ligne. Il vaut mieux faire cela plutôt que de tronquer le texte.
Le texte des étiquettes de case à cocher doit être concis. Si nécessaire, renvoyez le texte sur une deuxième ligne.
Ne tronquez pas le texte de l'étiquette de la case à cocher avec des points de suspension.
Utiliser un texte d'erreur pour guider les utilisateurs
Les groupes de cases à cocher et les cases à cocher peuvent inclure des messages d'erreur indiquant qu'une sélection est nécessaire pour avancer ou qu'une sélection effectuée n'est pas valide.
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 composant Case à cocher a 2 états principaux : non coché et coché. Par défaut, aucune des options n'est sélectionnée pour les cases à cocher.
Outre les états non coché et coché, les cases à cocher ont également des états interactifs pour **activé, désactivé, survol, focus, actif, ** et erreur.
Visuel
État
Description
Activé
Indique à l'utilisateur que l'élément est prêt à interagir (par défaut)
Désactivé
Indique à l'utilisateur que l'élément n'est actuellement pas disponible pour interagir.
Survol
Indique que l'utilisateur a positionné le curseur de la souris sur l'élément (uniquement sur la version pour ordinateur de bureau).
Focus
Indique que l'utilisateur a mis l'élément en surbrillance, généralement en utilisant une méthode de saisie comme un clavier ou la voix.
Actif
Indique que l'utilisateur clique ou appuie sur l'élément.
Erreur
Indique que l'utilisateur n'a pas coché tous les champs obligatoires (ou toute autre erreur liée au formulaire).
Les utilisateurs peuvent sélectionner une option en cliquant sur la case à cocher elle-même ou sur son étiquette. Les études montrent qu'il est plus rapide de cliquer sur une cible plus grande.
Lorsque la case à cocher est mise en évidence, appuyer sur la touche Espace modifie l'état de la case à cocher. Ceci suit les normes établies par le World Wide Web Consortium (W3C).
Pour le groupe de cases à cocher : le groupe de cases à cocher implémente <input type='checkbox'>. Le nom accessible du groupe est dérivé de son étiquette. Cette particularité peut être modifiée via le champ d'étiquette dans Storybook. Une association « for/id » est implémentée pour associer chaque case à cocher à son libellé, tandis que l'état « checked/unchecked » de l'élément est communiqué via l'attribut aria-checked.
Pour la case à cocher unique : l'élément de case à cocher est associé, par programmation, à son étiquette. Cela signifie que les utilisateurs peuvent utiliser la touche de tabulation pour parcourir les éléments et que leurs étiquettes respectives seront énoncées par les lecteurs d'écran. L'état « coché/décoché » est communiqué via l'attribut aria-checked.
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.
Le libellé des cases à cocher doit être clair et concis.
Si la sélection d'une case à cocher entraîne un changement de contexte, les utilisateurs doivent en être informés.
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.
State of the checkbox. If set to true, the checkbox is checked. Takes precedence over initialChecked. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes.
If set to true, the component is rendered in disabled state. Note that when checkbox group is disabled all checkboxes inside group are disabled as well.
Vous pouvez utiliser des attributs de saisie HTML, sauf ceux qui sont remplacés par Jutro. Ces attributs sont attribués à l'élément HTML input.
<CheckboxGrouplabel="This is a group"> <Checkbox label="This is the first one" id="firstOption" /> <Checkbox label="This is the second one" id="secondOption" /> <Checkbox label="This is the third one" id="thirdOption" /> </CheckboxGroup>
Il résulte de la transmission de la propriété id qu'elle fera partie de l'élément HTML input créé dans le DOM HTML.
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 :
Au lieu d'avoir une propriété value, le composant Checkbox utilise la propriété checked pour stocker les informations indiquant si elle est marquée ou non.
Priorité des propriétés disabled, displayOnly et readOnly
Si au moins deux des propriétés disabled, displayOnly, et readOnly sont définies sur true en même temps, l'ordre de préséance suivant s'applique :
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 Checkbox peut être utilisé seul, en dehors du contexte CheckboxGroup.
<Checkboxlabel="This is a single checkbox"/>
Cases à cocher de base dans un groupe de cases à cocher
Le composant CheckboxGroup fait office de conteneur pour un ensemble d'éléments Checkbox. Vous pouvez choisir d'afficher ou de masquer l'étiquette, mais elle est obligatoire pour l'accessibilité du composant.
<CheckboxGrouplabel="This is a group"> <Checkboxlabel="option 1"/> <Checkboxlabel="option 2"/> </CheckboxGroup>
Vous pouvez masquer l'étiquette CheckboxGroup en définissant la propriété hideLabel sur true. Cela n'affecte aucun des autres comportements de l'élément CheckboxGroup.
<CheckboxGroup label="This is only for aria-label" hideLabel={true}> <Checkboxlabel="option 1"/> <Checkboxlabel="option 2"/> </CheckboxGroup>
Les deux composants permettent aux développeurs d'afficher des messages d'erreur. Lorsqu'ils sont définis sur le niveau CheckboxGroup, les erreurs sont affichées sous toutes les options. Toutefois, lorsqu'ils sont définis sur le niveau Checkbox dans un CheckboxGroup, le message est ignoré et n'a aucun effet.
exportfunctionCheckboxMessages(){ const[validationMessages, setValidationMessages]=useState({}); const[groupValidationMessages, setGroupValidationMessages]=useState({}); const onChange =useCallback((e, newChecked)=>{ setValidationMessages({}); setGroupValidationMessages({}); if(newChecked){ setValidationMessages({error:['This is ignored']}); setGroupValidationMessages({error:['Only second checkbox can be marked']}); } },[]); return( <CheckboxGroup label="Do not select the forbidden option" stateMessages={groupValidationMessages} > <Checkbox label="Forbidden option" onChange={onChange} stateMessages={validationMessages} /> <Checkboxlabel="You can select this one"/> </CheckboxGroup> ); } }
Bien que cela ne soit pas implémenté dans le cadre du composant Checkbox, le comportement natif d'un élément d'entrée HTML est disponible. Dans ce cas, l'état indéterminé peut être défini par programmation via JavaScript. Une case à cocher à l'état indéterminé comporte une ligne horizontale dans la zone, au lieu d'une coche. Dans l'exemple ci-dessous, le style est modifié pour rendre l'option visible.
exportfunctionSetIndeterminateState(){ const onChange =useCallback((e, newCheck)=>{ (document.getElementById('checkbox2')asHTMLInputElement).indeterminate= newCheck; },[]); const style ={ opacity:100}; return( <CheckboxGrouplabel="Group of checkboxes"> <Checkbox label="Set the next checkbox as 'indeterminate'" onChange={onChange} /> <Checkbox label="This is another checkbox" id="checkbox2" checked={false} style={style} /> </CheckboxGroup> ); }
Vous pouvez ajouter des informations contextuelles aux composants CheckboxGroup et Checkbox à l’aide de leurs propriétés personnalisées.
La propriété secondaryLabel accepte un objet intlMessageShape pour afficher un contexte supplémentaire sous l’étiquette principale.
La propriété tooltip accepte soit un objet intlMessageShape, soit un objet personnalisé. Utilisez-la pour afficher une infobulle contenant des informations supplémentaires. Vous pouvez modifier le comportement de l’infobulle à l’aide de l’objet personnalisé.
<CheckboxGroup label="This is a group" tooltip="Select one of the available options" secondaryLabel="This label provides additional context."> <Checkbox tooltip="By selecting this option, you enable feature X." label="Option 1" value="1" /> <Checkbox tooltip={{text:"By selecting this option, you enable feature Y.",trigger:"pointerover"}} label="Option 2" value="2" secondaryLabel="This label provides additional context." /> </CheckboxGroup>
Ajout de la propriété secondaryLabel au composant Checkbox. Cette propriété vous permet d’ajouter une étiquette supplémentaire associée à chaque case à cocher.
Nouveaux composants @jutro/components/Checkbox et @jutro/components/CheckboxGroup introduits qui remplacent CheckboxField et CheckboxGroupField.
Les précédents composants liés à la case à cocher sont obsolètes et déplacés vers le package @jutro/legacy. Pour afficher leur documentation, passez à une version antérieure.
