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.
Lorsqu'il existe plusieurs options à sélectionner indépendamment les unes des autres. Utilisez plutôt la case à cocher.
Il existe un grand nombre d'options (6 ou plus) parmi lesquelles les utilisateurs peuvent choisir. Utilisez plutôt le composant Élément déroulant.
L'utilisateur peut ne sélectionner aucune option ou changer d'avis et désélectionner une option. Dans des cas comme celui-ci, envisagez d'utiliser le composant de case à cocher. Vous pouvez également choisir d'ajouter une option Aucune des options ci-dessus au groupe de boutons d'option à la place.
Note: Pour afficher un ensemble d'options mutuellement exclusives parmi lesquelles une personne peut en sélectionner une seule, utilisez des boutons d'option au lieu de cases à cocher.
Étiquette du groupe de cases d'option : explique l'objectif du groupe de cases d'option.
Texte d'aide (facultatif) : donne un contexte supplémentaire pour le groupe de cases d'option.
Entrée Bouton d'option : indique l'état approprié. Par défaut, une option est sélectionnée.
Étiquette Bouton d'option : décrit les informations à sélectionner ou à désélectionner.
Icône d'infobulle (facultatif) : permet de lever toute ambiguïté sur le contexte d'une case d'option donnée. L'infobulle apparaît lorsque vous la survolez.
Un groupe de cases d'option peut être organisé verticalement ou horizontalement en fonction de la structure de la page. Par défaut, les groupes de boutons d'option sont disposés verticalement pour faciliter la lecture.
Comme c'est le cas pour tous les composants de saisie, l'étiquette du groupe de cases d'option peut apparaître en haut (par défaut) ou à gauche de l'entrée elle-même.
Configurez l'une des cases d'option, généralement la première, de façon à ce qu'elle soit sélectionnée par défaut. Cette sélection accélère la tâche en indiquant à l'utilisateur qu'il doit choisir une option parmi cet ensemble. Il est recommandé d'indiquer une sélection par défaut dans la plupart des cas d'utilisation.
Toutefois, dans certains cas, la présélection d'une valeur par défaut est présomptueuse et peut entraîner une entrée incorrecte. Tenez compte du contenu et de la sélection par défaut, de la réaction des utilisateurs et de l'effet que la sélection aura sur l'utilisateur et l'organisation à court et à long terme. Évitez les sélections par défaut présomptueuses, insistantes, offensantes ou aliénantes.
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.
Utilisez un langage simple. Évitez tout jargon inutile et les formulations complexes.
Utilisez des termes et des phrases concis.
À utiliser pour des options mutuellement exclusives
Les boutons d'option et les cases à cocher ne sont pas interchangeables. Utilisez les boutons d'option pour sélectionner une **option unique ** parmi un petit ensemble d'options mutuellement exclusives (5 ou moins). Utilisez les cases à cocher lorsqu'il existe des listes d'options et que l'utilisateur peut sélectionner un nombre illimité de choix, y compris zéro, un ou plusieurs.
Utilisez des cases d'option lorsqu'un seul élément peut être sélectionné.
N'utilisez pas de cases d'option lorsque plusieurs éléments peuvent être sélectionnés.
Les groupes de cases d'option doivent avoir une étiquette qui décrit clairement ce que représente la liste d'options. Un groupe de cases d'option sans étiquette est ambigu et n'est pas accessible.
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.
Faites en sorte que les étiquettes des cases d'options soient concises
Limitez le texte de l'étiquette de la case d'option à une seule ligne. Nous vous recommandons d'utiliser de un à trois mots pour les étiquettes des cases d'option.
N'utilisez pas de points de suspension (...) pour tronquer le texte de l'étiquette de la case d'option. Si le texte de l'étiquette est trop long pour l'espace horizontal disponible, envisagez de le reformuler. Si les étiquettes des cases d'option 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.
Faites en sorte que le texte de l'étiquette de la case d'option soit concis. Si nécessaire, renvoyez le texte sur une deuxième ligne.
N'utilisez pas de points de suspension (...) pour tronquer le texte de l'étiquette de la case d'option.
Proposez plusieurs options distinctes et complètes
Les utilisateurs ne peuvent effectuer qu'une seule sélection dans un groupe de cases d'option. Cela signifie que chaque choix doit être clair et distinct. Évitez que les options se chevauchent visuellement.
Assurez-vous que les options soient clairement distinctes.
Ne fournissez pas d'options dont les valeurs se chevauchent.
Assurez-vous que la liste d'options que vous proposez est complète afin que les utilisateurs puissent faire une sélection. S'il n'est pas possible d'être exhaustif, proposez un bouton intitulé Autre, complété par un champ de saisie.
Assurez-vous que les options couvrent toutes les possibilités.
Ne fournissez pas un ensemble incomplet d'options.
Utiliser le texte d'erreur pour guider les utilisateurs
Les groupes de cases d'option peuvent inclure des messages d'erreur indiquant qu'une sélection est requise pour avancer ou que la 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.
Vous ne pouvez ajouter un astérisque qu'au groupe de cases d'option, pas aux options.
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 de case d'option a 2 états principaux : sélectionné et désélectionné. La vue par défaut d'un groupe de cases d'option permet de présélectionner l'une des cases d'option.
Les utilisateurs ne peuvent sélectionner qu'une seule case d'option à la fois. Lorsqu'un utilisateur effectue une nouvelle sélection, le choix précédent est automatiquement désélectionné.
État sélectionné
État non sélectionné
Les cases d'option ont également des états pour activé, survol, focus, actif, désactivé, et erreur.
Visuel
État
Description
Activé
Indique à l'utilisateur que l'élément est prêt à interagir (par défaut).
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.
Désactivé
Indique à l'utilisateur que l'élément n'est actuellement pas disponible pour interagir.
Erreur
Indique qu'une erreur s'est produite au niveau de cet élément. Par exemple, une sélection doit être effectuée pour pouvoir avancer, ou la sélection effectuée n'est pas valide.
Les utilisateurs utilisent les touches fléchées pour naviguer entre les différentes cases d'option. Pour sélectionner une case d'option, les utilisateurs appuient sur la touche ENTRÉE ou la barre d'espace.
Le groupe de cases d'option implémente le code html <input type="radio">, complété par WAI ARIA afin que cela soit compréhensible pour les utilisateurs aveugles. Le groupe est désigné comme tel par role='radiogroup', tandis que aria-checked bascule entre 'true' et 'false', en fonction de l'état de la case d'option. Une programmation associe les étiquettes et les cases d'option à partir d'une association 'for/id'. La valeur par défaut aria-required passe de 'false' à 'true' 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 vos applications, assurez-vous des points suivants :
Si un groupe de cases d'option ne dispose d'aucune valeur par défaut sélectionnée, le focus se déplace vers la première case d'option du groupe.
Les étiquettes doivent être placées après la case d'option.
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.
Position of radio group label, relative to radio options. 'top' - label will be placed above the option. 'left' - label will be placed on the left side of the options.
Value of the component. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.
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.
<RadioGrouplabel="This is a group"> <Radio label="This is the first one" value="1" id="firstOption" /> <Radio label="This is the second one" value="2" id="secondOption" /> <Radio label="This is the third one" value="3" id="thirdOption" /> </RadioGroup>
Après la transmission de la propriété id, elle fera partie du input HTML 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 :
Le composant Radio ne doit pas être utilisé seul, il ne doit être utilisé que dans le cadre du composant RadioGroup. Le composant RadioGroup accepte uniquement des éléments Radio en tant qu'éléments enfants.
Warning: Toute utilisation différente de celles décrites ci-dessus n'est pas prise en charge et peut entraîner des problèmes inopinés dans les versions futures.
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.
Radio ne peut pas être utilisé seul, en dehors du contexte RadioGroup. RadioGroup ne doit recevoir que des composants Radio en tant qu'enfants. La propriété label est obligatoire dans les deux composants et la propriété value est requise pour le composant Radio uniquement.
<RadioGrouplabel="This is a group"> <Radio label="option 1" value="1" /> <Radio label="option 2" value="2" /> </RadioGroup>
Case d'option désactivée vs Groupe de cases d'option désactivé
Les deux composants fournissent une propriété disabled. Toutefois, lorsqu'elle est définie sur true au niveau RadioGroup, elle remplace toute configuration de désactivation du niveau Radio. S'il existe un paramètre de propriété disabled={false} parmi les options Radio, mais que le RadioGroup le définit sur disabled={true}, toutes les options sont désactivées.
<RadioGroup label="This is a group" disabled={true}> <Radio label="option 1" value="1" disabled={false} /> <Radio label="option 2" value="2" disabled={false} /> </RadioGroup>
Il est possible de définir quelle option est initialement sélectionnée en transmettant la propriété value à la propriété initialValue du RadioGroup.
<RadioGroup label="This is a group with second option selected initially" initialValue="2"> <Radio label="option 1" value="1" /> <Radio label="option 2 is initially selected" value="2" /> </RadioGroup>
Le composant RadioGroup 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é.
exportfunctionRadioValidation(){ const[groupValidationMessages, setGroupValidationMessages]=useState({}); const onChange =useCallback((e, newValue)=>{ setGroupValidationMessages({}); if(newValue =='1'){ setGroupValidationMessages({ error:['Only second option can be marked'], }); } },[]); return( <RadioGroup label="Do not select the forbidden option" onChange={onChange} stateMessages={groupValidationMessages}> <Radio label="Do not select the forbidden option" value="1" /> <Radio label="This option can be selected" value="2" /> </RadioGroup> ); }
RadioGroup et certaines autres entrées vous permettent d'utiliser une propriété ref pour accéder à certains comportements natifs. Toutefois, seules certaines fonctionnalités sont exposées. Dans ce cas, lorsque vous cliquez sur le bouton, le focus est automatiquement défini dans l'entrée ci-dessous.
<RadioGroup label="This is a group with second option selected initially" initialValue="2"> <Radio label="option 1" value="1" /> <Radio label="option 2 is initially selected" value="2" /> </RadioGroup>
Vous pouvez ajouter des informations contextuelles aux composants RadioGroup et Radio à 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é.
<RadioGroup label="This is a group" tooltip="Select one of the available options" secondaryLabel="This label provides additional context."> <Radio tooltip="By selecting this option, you enable feature X." label="Option 1" value="1" /> <Radio tooltip={{text:"By selecting this option, you enable feature Y.",trigger:"pointerover"}} label="Option 2" value="2" secondaryLabel="This label provides additional context." /> </RadioGroup>
Ajout de la propriété secondaryLabel au composant Radio. Cette propriété vous permet d’ajouter une étiquette supplémentaire associée au champ d’option.
Suppression de la propriété inutilisée readOnly des composants RadioGroup et Radio. Cette propriété n'avait pas de fonction et a été exposée par erreur.
De nouveaux composants @jutro/components/RadioGroup et @jutro/components/Radio ont été introduits. Ces composants remplacent d'autres composants existants liés au bouton Radio, à savoir RadioButtonField, RadioButtonCardField, ImageRadioButtonField, RadioField et RadioGroup.
Les précédents composants liés au bouton Radio sont obsolètes et ont été déplacés vers le package @jutro/legacy. Pour consulter leur documentation, passez à une version antérieure de la documentation antérieure.
