Passer au contenu principal

Portes de sortie

Présentation​

Les spécifications UX de Jutro Design System sont basées sur les cas d'utilisation UX identifiés et décrivent les problèmes et les exigences, ainsi que les approches recommandées et les directives pour les couvrir. Les différents composants Jutro sont conçus dans le but d'être alignés sur ces spécifications UX et l'ensemble des propriétés et fonctionnalités fournies sont basées sur celles-ci.

Bien que l'objectif principal des composants soit l'alignement de l'expérience utilisateur, ils fournissent également des alternatives personnalisées qui peuvent permettre aux développeurs d'aller au-delà du comportement par défaut, et c'est là que les portes de sortie sont introduites.

Qu'est-ce qu'une porte de sortie ?​

« Porte de sortie » est un terme adopté dans le développement logiciel pour faire référence aux alternatives intentionnelles (fuites) présentes dans le modèle qui permettent aux utilisateurs de « sortir » et d'accéder à une couche d'abstraction inférieure. Cela pourrait même être considéré comme une porte ouverte pour « pirater » le contrat d'abstraction spécifique.

Par exemple, les portes de sortie React sont pertinentes pour les développeurs Jutro

Portes de sortie de Jutro Design System​

Warning: Avertissement

Tenez compte des effets secondaires possibles de toute porte de sortie utilisée. Bien qu'elles fournissent un mécanisme permettant d'étendre un comportement ou de réduire les écarts d'exigences, elles peuvent avoir des effets inattendus en fonction de leur utilisation. Certains effets potentiels peuvent être des fonctionnalités endommagées, des problèmes d'accessibilité et de futures complications de mise à niveau.

Chaque composant Jutro peut fournir des portes de sortie différentes, selon le cas d'utilisation et le type de composant. Dans certains cas, elles sont fournies dans le cadre de l'API stable du composant, mais incluses en tant que portes de sortie, car elles fournissent des options qui permettent une flexibilité supplémentaire en plus de l'alignement des spécifications UX.

Vous trouverez ci-dessous des descriptions de certaines des portes de sortie les plus courantes fournies par les composants Jutro. Pour les portes de sortie propres aux composants, consultez la documentation des composants.

Jetons de conception​

Bien qu'ils fassent partie de l'API des composants Jutro, les jetons de conception peuvent être considérés comme une porte de sortie, car ils permettent de personnaliser la décision d'expérience utilisateur liée au thème.

Reportez-vous à la section Jetons de conception pour en savoir plus.

Propriétés dangerouslySet​

Certains composants incluent une ou plusieurs propriétés dangerouslySet.... Ceux-ci permettent au développeur de remplacer complètement un élément/un aspect entier du composant. Dans la plupart des cas, cette option est fournie lorsque les spécifications UX identifient un cas limite incluant des alternatives inconnues.

La propriété dangerouslySet sera saisie en tant que ReactNode et, normalement, il y aura un crochet associé pour fournir l'accès au contexte du composant.

Exemple : l'en-tête AccordionCard n'aura normalement qu'un texte (propriété title) mais il existe un besoin connu d'avoir d'autres éléments tels que des icônes, des balises ou même des boutons dans certains cas spécifiques, de sorte qu'une propriété dangerouslySetHeader sera fournie.



function MyCustomHeader() {
   const { disabled } = useComponentState(); // provided hook for context information
   return <span>{disabled ? 'I am disabled' : 'I am not disabled'}</span>;
}


<AccordionCard title="some title" dangerouslySetHeader={{<MyCustomHeader />}}/>

Propriété children​

Bien qu'en général, chaque propriété de composant soit saisie pour limiter les valeurs et les options fournies, dans certains cas, elle peut rester complètement ouverte (via children: ReactNode). Le scénario le plus courant dans ce cas est celui des composants qui sont principalement destinés à être utilisés comme conteneurs pour d'autres contenus (par exemple, les modaux).

Propriété className​

Les composants Jutro s'affichent généralement avec un attribut de classe HTML prédéfini. Certains composants peuvent fournir une propriété className qui ajoute une classe à l'élément de niveau supérieur du composant. Par exemple, <DatePicker className="foo"> aura un élément parent avec une classe qui ressemble à <div class="foo fieldContainer_TIDj">.

Sélecteurs utilisant la structure HTML sous-jacente​

Si vous souhaitez formater des éléments HTML spécifiques d'un composant rendu, vous pouvez inspecter la structure HTML sous-jacente générée et utiliser les sélecteurs CSS qui les sélectionnent. Par exemple, pour mettre en gras le texte dans tous les éléments HTML label rendus par <DatePicker className="foo">, vous pouvez utiliser la syntaxe suivante :

.foo label {
   font-weight: bold;
   }
Warning: Avertissement

La structure HTML sous-jacente d'un composant ne fait pas partie de l'API du composant. Elle peut donc faire l'objet de modifications qui ne soient pas considérées comme majeures. Bien que l'élément de niveau supérieur du composant reste stable, le reste de la structure interne peut être modifié.

Sélecteurs utilisant des attributs de classe prédéfinis​

Vous pouvez également utiliser l'attribut de classe prédéfini à la place de className. Par exemple, sans une propriété className, votre DatePicker ressemblera à <div class="fieldContainer_TIDj">. Son élément label peut être sélectionné à l'aide de cet attribut de classe prédéfini avec la syntaxe suivante :

.fieldContainer_TIDj label {
   font-weight: bold;
   }

La plupart des éléments internes ont également des attributs de classe HTML prédéfinis. Vous pouvez également les utiliser pour créer des sélecteurs CSS. Par exemple, si l'élément label rendu ressemble à ceci :

<label class="labelContainer_wEwV"><span>Choose date</span></label>

Ensuite, vous pouvez utiliser la syntaxe suivante pour le sélectionner :

.labelContainer_wEwV {
   font-weight: bold;
   }
Warning: Avertissement

Les attributs de classe HTML prédéfinis ne font pas partie de l'API du composant, y compris l'attribut de classe prédéfini du composant de niveau supérieur. Ces valeurs peuvent donc faire l'objet de modifications qui ne soient pas considérées comme majeures.

Si vous utilisez les attributs de classe prédéfinis dans votre code, ils peuvent changer entre les mises à jour, ce qui doit être pris en compte.

Autoriser la transmission des attributs HTML par défaut​

Outre l'API définie par Jutro, certains composants permettent de transmettre un ensemble supplémentaire d'attributs HTML natifs que le composant peut comporter. Ces attributs supplémentaires seront directement transmis à l'élément de niveau supérieur ou à l'élément spécifique spécifié dans la documentation du composant.

Voici un exemple de ce cas d'utilisation : certains composants Jutro « d'entrée » peuvent autoriser la transmission des attributs HTML standard qu'un élément HTML natif input accepterait : par exemple id ou name. La liste des attributs peut être restreinte pour éviter que ces attributs n'interfèrent avec les propriétés et le comportement du composant. Par exemple, si le composant gère déjà la longueur maximale acceptée de son contenu, l'attribut natif maxLength peut ne pas être accepté.

Comme dans d'autres cas, les effets secondaires des attributs utilisés doivent être pris en compte lors de leur utilisation.

Note: Lors de la création d'un nouveau champ, vous ne devez pas utiliser la propriété ID. Les nouveaux champs génèrent un ID unique en interne. Si vous souhaitez créer votre propre ID, vous pouvez utiliser le crochet useId à partir de @jutro/platform pour vous assurer que l'ID est unique. Reportez-vous à la page Crochets pour en savoir plus sur le crochet useId.

Propriété ref et gestionnaires impératifs​

ref est une porte de sortie qui permet d'accéder aux nœuds DOM ou aux composants React pour permettre aux développeurs de modifier des éléments en dehors du flux de rendu. Dans le cas de Jutro, cette option peut être envisagée dans certains composants spécifiques, mais elle sera normalement implémentée selon l'approche du gestionnaire impératif : au lieu de simplement fournir un accès à l'ensemble de l'élément, des méthodes ou des propriétés spécifiques seront exposées en fonction des cas d'utilisation connus. Elles peuvent évoluer et augmenter dans les versions futures de la bibliothèque.

La création d'une propriété ref qui fournit uniquement un accès à des fonctionnalités spécifiques, telles que la définition du focus sur un champ ou le défilement vers l'élément spécifique, est un exemple de cette option.

Propriété d'événement natif​

Les composants d'entrée Jutro exposeront certains événements tels que onChange. Ces événements incluent normalement, outre toute autre valeur personnalisée, l'objet natif event qui a déclenché l'événement.

Il est attendu que, normalement, les valeurs personnalisées transmises à l'événement fournissent suffisamment d'informations au développeur, mais event permettra un contrôle plus poussé de certaines fonctionnalités de base, telles que preventDefault.

À titre d'exemple, un événement onChange serait défini comme (event: React.ChangeEvent<HTMLInputElement>, newValue: T) => void, afin que le développeur puisse simplement utiliser newValue pour effectuer des validations ou des actions en fonction de la saisie de l'utilisateur, mais l'événement natif est également disponible pour toute fonctionnalité supplémentaire.