Fermer

mai 5, 2021

Guide ultime pour créer une bibliothèque de composants d'interface utilisateur – Partie 310 minutes de lecture



Voyons comment créer des composants d'interface utilisateur robustes! Nous verrons quand coder des composants et quand construire sur des bibliothèques tierces, une structure de test unitaire pour vos composants et quelques options pour écrire la documentation de vos composants.

Cet article est la troisième partie d'une série sur la création d'une bibliothèque complète de composants d'interface utilisateur pour votre organisation. Si vous avez trouvé cet article en premier, vous voudrez peut-être lire partie 1 et partie 2 avant de continuer.

Dans la partie 1 de cette série, vous avez appris à planifier une bibliothèque de composants d'interface utilisateur , et dans la deuxième partie, vous avez appris à configurer un environnement de développement pour coder les composants de votre bibliothèque.

Dans cet article, nous allons nous concentrer sur l'écriture des composants de l'interface utilisateur eux-mêmes. Nous allons commencer par une discussion sur le moment de coder des composants à la main et sur le moment de créer des bibliothèques tierces. Ensuite, nous allons mettre en place une structure de test unitaire pour vos composants et écrire quelques tests avec. Et enfin, nous terminerons en montrant quelques options dont vous disposez pour rédiger la documentation de vos composants.

Il y a beaucoup à discuter, alors commençons par parler de quand coder des composants vous-même, et quand utiliser des bibliothèques tierces

Table des matières

Quand utiliser des bibliothèques tierces

Construire une bibliothèque de composants complète pour une grande entreprise implique souvent la création de dizaines (voire de centaines) de composants d'interface utilisateur. La création de ces composants peut prendre énormément de temps, en particulier une fois que vous dépassez les composants de base comme les entrées et les boutons, et que vous commencez à avoir besoin de composants avancés tels que les sélecteurs de date, la saisie semi-automatique, les boîtes de dialogue, etc.

Vous pouvez vous simplifier la vie en utilisant le composant d'interface utilisateur existant bibliothèques, car il existe de nombreux sélecteurs de date, autocomplétions et boîtes de dialogue de haute qualité disponibles sur npm. Mais l'ajout de dépendances sur d'autres bibliothèques présente des inconvénients, comme des ensembles côté client plus volumineux que vos utilisateurs peuvent télécharger et avoir moins de contrôle sur la personnalisation de vos composants.

Alors, que faites-vous? J'ai quelques recommandations lorsque vous décidez d'utiliser ou non une bibliothèque.

Recommandation n ° 1: Lean Toward Libraries for Complex Components

La plupart des développeurs frontaux peuvent créer un composant bouton de haute qualité dans un délai raisonnable

Mais presque tous les développeurs auront du mal à créer un calendrier ou une grille de données – et même s'ils sont capables, il leur faudra des semaines ou des mois pour en créer un avec les fonctionnalités dont votre entreprise a besoin. (Et encore plus de temps si vous voulez que ces composants soient accessibles, bien documentés, etc.)

Bien qu'il puisse être tentant de prendre le temps de construire vous-même un composant complexe, dans la plupart des situations, il vaut mieux tirer parti le travail déjà effectué par une autre bibliothèque, et gagner du temps pour travailler sur des fonctionnalités propres à votre entreprise.

Il existe des exceptions à cela. Par exemple, si vous travaillez pour une entreprise qui crée des calendriers, il peut être judicieux de créer votre propre contrôle de calendrier, car il est essentiel pour votre entreprise et vous devez probablement personnaliser fortement. Mais dans la plupart des situations, il est logique de dépendre des bibliothèques existantes pour les composants complexes.

Recommandation n ° 2: Enveloppez vos dépendances tierces

La bibliothèque de composants d'interface utilisateur que nous avons créée dans cette série d'articles est conçue pour être utilisée par plusieurs autres applications dans une entreprise. En tant que tel, lorsque vous ajoutez une dépendance à votre bibliothèque de composants, vous ajoutez également cette dépendance à chaque application qui utilise votre bibliothèque.

Ce couplage peut être problématique si vous souhaitez changer de bibliothèque à l'avenir, car toute dépendance change dans la bibliothèque de composants oblige également tous les consommateurs de la bibliothèque à se mettre à jour.

Vous pouvez atténuer ce risque en encapsulant tous les contrôles tiers que vous utilisez avec votre propre API. Par exemple, supposons que vous souhaitiez utiliser un composant DatePicker d'une bibliothèque hypothétique de composants LibraryX.

Au lieu d'encourager les applications de votre entreprise à utiliser directement le DatePicker de LibraryX, ce qui ressemblerait à ceci:

 import  {DatePicker  as  LibraryDatePicker}  from   'LibraryX' ;

 < DatePicker  /> 

Vous pouvez à la place créer un wrapper du contrôle tiers dans votre bibliothèque de composants et faire en sorte que les applications de votre entreprise utilisent ce wrapper à la place. Voici un exemple de ce à quoi pourrait ressembler ce wrapper.

 import  {DatePicker  as  LibraryXDatePicker}  from   'LibraryX' ;

 const  DatePicker =  ( accessoires ) =>  {
   retour  (
     < LibraryXDatePicker  { ... accessoires } /> 
  );
}

export default DatePicker; 

En plus de faciliter le changement de bibliothèque à l'avenir, cette approche vous donne également un endroit consolidé pour contrôler tous les contrôles DatePicker dans toute votre organisation. Par exemple, si votre équipe de conception décide soudainement que tous les sélecteurs de date de votre entreprise doivent utiliser un format de date différent, vous disposez désormais d'un seul emplacement où vous pouvez effectuer cette modification et affecter tous les contrôles de sélecteur de date de votre organisation.

Recommandation 3: Limiter la Nombre de bibliothèques tierces que vous utilisez

Bien que l'utilisation de bibliothèques tierces présente de nombreux avantages, l'un des inconvénients est qu'il est souvent difficile de personnaliser les composants tiers pour qu'ils correspondent aux directives de conception de votre entreprise.

Ce problème se complique. avec chaque nouvelle bibliothèque que vous introduisez, car chaque bibliothèque a son propre auteur, et donc aussi sa propre approche pour déterminer la structure de balisage d'un composant, les noms de classe CSS et ainsi de suite qu'un composant utilise.

Pour cette raison, lorsque cela est possible, J'encourage les développeurs à se tourner vers des bibliothèques qui offrent plusieurs composants qui utilisent le même design (par exemple Material-UI, Ant Design, KendoReact), plutôt que d'essayer d'intégrer plusieurs petits composants qui vous devez déterminer manuellement comment travailler ensemble.

Il existe également des exceptions à cette règle. Si vous trouvez un composant sur mesure sur npm qui résout parfaitement votre problème, et que vous ne trouvez aucune alternative dans des bibliothèques plus grandes, alors utilisez-le absolument. Mais en général, il est judicieux de limiter le nombre de dépendances que vous utilisez lorsque cela est possible.

Recommandation n ° 4: Rechercher des bibliothèques dont l'accessibilité est intégrée

La création d'une bibliothèque de composants d'entreprise vous donne un emplacement unique pour implémenter l'accessibilité de l'interface utilisateur pour vos commandes. Autrement dit, si vous créez des composants accessibles dans votre bibliothèque, toutes vos applications d'entreprise qui utilisent votre bibliothèque bénéficient de ces avantages d'accessibilité «gratuitement», ce qui est génial!

Cela signifie qu'il est important d'obtenir l'accessibilité directement dans vos composants. . Et par conséquent, il vaut également la peine de vous assurer que toute bibliothèque que vous utilisez adhère aux meilleures pratiques d'accessibilité.

Avec ces recommandations pour travailler avec les bibliothèques de composants d'interface utilisateur à l'esprit, voyons maintenant comment mettre ces conseils en pratique et créer un composant pour votre bibliothèque qui utilise une dépendance tierce.

Comment créer des composants qui utilisent des bibliothèques tierces

Si vous avez suivi la partie 2 de cette série d'articles vous devriez avoir une petite bibliothèque de composants configurée qui comprend un bouton et un composant d'entrée.

Les boutons et les entrées sont relativement simples, alors voyons maintenant comment créer un sélecteur de date, qui est un composant beaucoup plus complexe que la plupart des entreprises ne voudront pas

Il existe de nombreux sélecteurs de date React, mais pour cet article, nous utiliserons le KendoReact DatePicker à la fois parce que KendoReact fournit une grande variété de composants et parce que KendoReact adhère à de nombreuses normes d'accessibilité . Cela étant dit, les conseils de cette section s'appliquent à d'autres composants tiers sur lesquels vous voudrez peut-être construire.

REMARQUE: KendoReact est une bibliothèque payante qui nécessite une licence d'utilisation en production. Vous pouvez démarrer une version d'évaluation gratuite de 30 jours si vous souhaitez effectuer les étapes de cet article sans avertissement de licence.

Pour commencer, n'oubliez pas que la structure actuelle de votre bibliothèque de composants ressemble à ceci.

 .
├── démo
│ └── ...
└── src
    ├── Bouton  .js 
    ├── Entrée  .js 
    ├── thème  .css 
    └── ...

Pour commencer, allez-y et créez un nouveau fichier DatePicker.js dans votre répertoire src .

.
├── démo
│ └── ...
└── src
    ├── Bouton  .js 
    ├── DatePicker  .js  <- créer ceci
    ├── Entrée  .js 
    ├── thème  .css 
    └── ...

Ensuite, collez le code suivant, ce qui crée un nouveau composant DatePicker qui encapsule le contrôle KendoReact DatePicker.

 import  React  from   'react' ;
 import  {DatePicker  comme  KendoDatePicker}  de   '@ progress / kendo-react-dateinputs' ;

 const  DatePicker =  ( accessoires ) =>  {
   retour  (
     < KendoDatePicker  { ... accessoires } /> 
  )
}

export default DatePicker; 

Lorsque vous enregistrez ce fichier, des erreurs peuvent survenir dans votre éditeur, car vous faites référence à un package @ progress / kendo-react-dateinputs qui n’existe pas encore. Pour résoudre ce problème, accédez à votre terminal et placez d'abord le cd dans votre répertoire src (si vous ne l'avez pas déjà fait).

  cd  src

Ensuite, exécutez la commande suivante pour installer @ progress / kendo-react-dateinputs ainsi que ses dépendances.

  npm  install @ progress / kendo-react-dateinputs @ progress / kendo-licensing @ progress / kendo-react-intl

Une fois cette dépendance installée, vous êtes prêt à exécuter votre build pour compiler votre nouveau composant DatePicker. Pour ce faire, assurez-vous que vous êtes toujours dans votre répertoire src et exécutez la commande suivante.

 npm  run   build 

Cette commande compilera votre nouveau composant, et placez le fichier produit dans votre répertoire dist .

Pour utiliser ce composant dans votre démo, ouvrez votre fichier demo / src / App.js et remplacez son contenu par code ci-dessous.

 import  DatePicker  de   'acme-components / DatePicker' ;
 import   'acme-components / theme.css' ;

 fonction   Application  ()  {
   retour  (
     <> 
       < h1 >  Composants ACME  </  h1 > 
       < DatePicker  /> [19659069]);
}

exporter l'application par défaut; 

Ensuite, retournez à votre terminal ou à l'invite de commande et accédez au répertoire demo de votre projet.

   cd   ../ demo

Ensuite, installez les mêmes dépendances de KendoReact DatePicker.

  npm  install @ progress / kendo-react-dateinputs @ progress / kendo-licensing @ progress / kendo-react-intl

Et enfin, tout en restant dans votre répertoire demo utilisez la commande suivante pour exécuter votre application de démonstration.

 npm  run   start 

REMARQUE: You peut recevoir des avertissements sur l'utilisation de KendoReact sans licence à cette étape. S'ils vous ennuient, vous pouvez les supprimer en en configurant votre clé de licence KendoReact .

Lorsque vous exécutez cette commande, vous verrez votre nouveau DatePicker dans le navigateur, qui apparaît comme une entrée, mais ne ressemble pas encore tout à fait à un sélecteur de date.

 Composant DatePicker initial - une fenêtre blanche montre les composants d'ACME et une boîte simple en dessous qui dit «mois / jour / année»

Si vous utilisez votre les outils de développement du navigateur, vous verrez que KendoReact fonctionne en fait, car un certain nombre de noms de classe sont maintenant appliqués à votre entrée, mais aucun CSS n'est appliqué à votre balisage.

Pour résoudre ce problème, voyons ensuite comment implémenter CSS pour ce contrôle.

Comment implémenter CSS avec des bibliothèques tierces

À cause de cela, quand à l'aide de bibliothèques tierces, je recommande d'encapsuler des CSS tiers dans votre bibliothèque. La raison en est que vous ne voulez pas ses applications pour utiliser votre bibliothèque avec le moins d'étapes possible. Pour voir ce que je veux dire, allons-y et implémentons le CSS de DatePicker de KendoReact dans votre bibliothèque de composants.

Pour commencer, retournez à votre terminal ou à l'invite de commande et revenez à votre dossier src . [19659044] cd ../ src

Ensuite, installez le thème par défaut de KendoReact en utilisant la commande ci-dessous.

  npm   install  @  progress  /  kendo  -  theme  -  default 

ASTUCE: KendoReact propose à la fois des thèmes bootstrap et matériels que vous pourrez expérimenter plus tard.

Avec l'installation du thème à l'écart, votre prochain l'étape consiste à importer le CSS du thème dans votre bibliothèque. Rappelez-vous de l'article précédent de cette série que vous avez un fichier src / theme.css qui ressemble actuellement à ceci.

 .acme-button  {
   couleur :  # 444 ;
   fond : bleu clair;
   rembourrage :  0,5em ;
   border-radius :  4px ;
   text-shadow :  0   1px   1px   rgba  (0, 0, 0, 0,2);
   taille de police :  1,1em ;
}
 .acme-input  {
   rembourrage :  0,5em ;
   couleur :  # 444 ;
   taille de police :  1,1em ;
   border-radius :  4px ;
}

Ce fichier est l’endroit logique pour importer le CSS de KendoReact, mais comment procédez-vous exactement? Mon premier instinct en essayant ceci a été d'utiliser la syntaxe suivante:

 @  import   '@ progress / kendo-theme-default / dist / all.css' ;

.acme-button {...}
.acme-input {...}

Mais si vous essayez cette approche, votre application de démonstration ne reconnaîtra pas cette syntaxe, et votre application plantera avec l'erreur suivante.

  Erreur : Can  't résoudre' [19659103] @progress  /kendo-theme-default/dist/all.css  'dans'  / Users / tj / Desktop / acme-components / dist '

Le problème est que CSS à lui seul ne sait pas comment importer des fichiers à partir de node_modules . Pour ce faire, vous devez soit introduire quelque chose comme webpack, qui vous permet d'importer des fichiers depuis node_modules avec un caractère ~ ou vous devez utiliser un Préprocesseur CSS comme SASS.

Pour cet article, nous utiliserons SASS, car je préfère éviter les outils plus compliqués comme webpack sauf si j'en ai absolument besoin, et aussi parce que KendoReact lui-même utilise SASS, donc en utilisant SASS pour notre bibliothèque, nous pouvons optimisez le CSS que nous importons.

Pour installer SASS, vous devez d'abord l'installer dans votre dossier src (ainsi que dans un petit utilitaire copyfiles que vous utiliserez pour déplacer

 npm install sass copyfiles -  save  -  dev 

Ensuite, vous devez modifier vos scripts dans votre fichier package.json afin qu'ils exécutent maintenant le compilateur SASS. Pour ce faire, remplacez le bloc "scripts" existant dans votre fichier src / package.json par le code ci-dessous.

  "scripts" : {
   "build" :  "npm run build-js && npm run build-css" ,
   "build-js" :  "babel * .js --out-dir ../dist --copy-files && copyfiles * .json ../dist",
   "build-css" :  "sass theme.scss theme.css && copyfiles * .css ../dist",
   "montre" :  "montre npm" 
},

Cette modification ajoute un nouveau script "build-css" qui indique à SASS de compiler un fichier theme.scss dans un fichier theme.css . Cette modification met également à jour le script "build" de sorte qu'il déclenche à la fois une version JavaScript et CSS.

Une fois cette mise à jour en place, mettez à jour votre src / package.json ] configuration du fichier "watch" avec le code ci-dessous.

  "watch" : {
   "build-js" : {
     "modèles" : [
       "*. Js" 
    ],
     "extensions" :  ". Js" 
  },
   "build-css" : {
     "modèles" : [
       "*. Scss" 
    ],
     "extensions" :  ". Scss" 
  }
},

Cette modification indique à l'observateur que nous avons configuré dans l'article précédent de surveiller en outre les modifications apportées aux fichiers .scss et lorsqu'il détecte une modification, de déclencher le "build-css" .

Une fois la configuration terminée, recherchez ensuite votre fichier src / theme.css et renommez-le en theme.scss car il contiendra désormais le code SASS. Et enfin, ouvrez votre fichier theme.scss et placez l'importation suivante juste en haut.

 @  import   "node_modules / @ progress / kendo-theme-default / scss /datetime/_index.scss";

Cette ligne de code importe du CSS à partir du thème par défaut de KendoReact. Et comme KendoReact utilise SASS lui-même, ce code est également suffisamment intelligent pour importer uniquement les styles datetime de sorte que vous n'ayez pas à envoyer le CSS pour tous les composants de KendoReact à vos utilisateurs.

Et avec cela, vos modifications SASS sont terminées. Pour essayer tout cela, lancez d'abord une nouvelle version de votre code en exécutant la commande suivante à partir de votre répertoire src .

 npm  run   build 

Ensuite, revenez à votre répertoire demo .

   cd   ../ demo

Et puis lancez votre application pour essayer vos nouveaux styles.

 npm  run   start 

Si tout s'est bien passé, vous devriez voir votre composant DatePicker stylé correctement.

 ] Un sélecteur de date correctement stylé - un joli calendrier apparaît

Ce qui est cool ici, c'est que votre application de démonstration n'a pas du tout à se soucier du CSS – il suffit d'importer acme-components / theme .css et le reste s'est fait automatiquement.

Et vraiment, toute cette configuration de composants est assez puissante. Si vous avez suivi ce point de l'article, vous disposez désormais d'un flux de travail qui vous permet d'écrire des composants qui peuvent être manuscrits ou encapsulés dans des bibliothèques tierces – et vous pouvez prendre cette décision composant par composant .

Une fois cette configuration en place, discutons ensuite de l'un des autres aspects les plus délicats de tout environnement de développement: les tests unitaires.

Comment tester les unités de vos composants

Les tests unitaires sont importants dans n'importe quel environnement, mais c'est particulièrement important dans les bibliothèques de composants, car les contrôles que vous créez sont destinés à être utilisés dans toute votre organisation. Vous voulez donc vous assurer qu'ils fonctionnent correctement.

La bonne nouvelle est que la configuration que nous avons construite jusqu'à présent est une jolie environnement JavaScript standard, vous pouvez donc tester vos composants en utilisant à peu près n'importe quel outil de test unitaire que vous avez à l'esprit.

Pour cet article, nous utiliserons à la fois Jest et Testing Library , car il s'agit d'une configuration de test assez standard pour les applications React, et Testing Library est particulièrement bien adapté pour tester les composants de l'interface utilisateur.

Pour essayer les tests unitaires dans notre bibliothèque, ouvrez d'abord votre src / DatePicker.js et remplacez son contenu par le code suivant:

 import  React  from   'react' ;
 import  {DatePicker  comme  KendoDatePicker}  de   '@ progress / kendo-react-dateinputs' ;

 const  DatePicker =  ( {className, ... otherProps} ) =>  {
  className = className? ( "acme-datepicker"  + className):  "acme-datepicker" ;
   retour  (
     < KendoDatePicker 
      { ... otherProps }
       className  =  {className}  /> 
  )
}

export default DatePicker; 

Cette modification ajoute un accessoire className qui permet aux utilisateurs de transmettre des noms de classe CSS personnalisés, ainsi qu'un peu de logique garantissant qu'un acme-datepicker nom de classe se retrouve sur le DatePicker, qu’un nom de classe personnalisé soit passé ou non.

Cette logique est exactement le genre de chose qu'il est bon de vérifier avec un test unitaire.

Pour ce faire, commençons par installer à la fois Jest et Testing Library. Vous pouvez le faire en retournant à votre terminal ou à l'invite de commande et en exécutant les commandes suivantes.

  npm   install   jest  @  testing  -  bibliothèque  /  react  --save-dev

Ensuite, ouvrez votre fichier src / package.json et ajoutez une nouvelle commande "test": "jest" à votre configuration "scripts" . Le bloc complet "scripts" devrait maintenant ressembler à ceci.

  "scripts" : {
   "build" :  "npm run build-js && npm run build-css" ,
   "build-js" :  "babel * .js --out-dir ../dist --copy-files && copyfiles * .json ../dist",
   "build-css" :  "sass theme.scss theme.css && copyfiles * .css ../dist",
   "test" :  "plaisanterie" ,
   "montre" :  "montre npm" 
},

Avec cette configuration, vous pouvez maintenant exécuter npm run test pour déclencher Jest, qui trouve et exécute vos tests pour vous.

Pour démarrer nos tests, créez un nouveau src / DatePicker .test.js avec le contenu suivant, qui est actuellement simple pour que vous puissiez voir comment fonctionne Jest.

 test ('S'assurer que les maths fonctionnent', () => {
  expect ( 1  +  2 ). toEqual ( 3 )
})

Ensuite, retournez à votre terminal et exécutez votre nouvelle commande npm run test qui demande à Jest de rechercher et d'exécuter tous vos tests unitaires. Dans ce cas, Jest devrait trouver votre nouveau fichier DatePicker.test.js et afficher le résultat réussi suivant.

Vous pouvez en savoir plus sur le fonctionnement de Jest dans sa documentation .

Maintenant que vous avez Jest en place pour exécuter vos tests, voyons comment vous pouvez utiliser Testing Library pour testez vos composants eux-mêmes. Revenez à votre fichier src / DatePicker.test.js et remplacez son contenu par le code suivant.

 import  React  de   'react' ;
 import  {rendu, écran}  de   '@ testing-library / react' ;
 importation  DatePicker  de   './ DatePicker' ;

décrire ( 'DatePicker tests'  ()  =>  {
  test ( 'S'assurer que le nom de la classe acme est ajouté'  ()  =>  {
    rendu ();
    expect (screen.getByRole ( 'group' ). classList.contains ( 'acme-datepicker' ));
  });

  test ( 'Assurez-vous que les noms de classes supplémentaires sont ajoutés'  ()  =>  {
    render (<DatePicker className =  "toto"  />);
    const picker = screen.getByRole ( 'groupe' );
    expect (picker.classList.contains ( 'acme-datepicker' ));
    expect (picker.classList.contains ( 'foo' ));
  });
});

Alors que Jest offre la possibilité d'exécuter vos tests, ainsi que des méthodes comme describe () et test () pour les organiser, Testing Library fournit un certain nombre de méthodes qui permettent tester facilement vos composants eux-mêmes.

Par exemple, la méthode render () de Testing Library vous permet de «rendre» un composant, puis de rechercher des éléments individuels de votre composant avec des méthodes telles que screen.getByRole () et effectuer des vérifications. Le code ci-dessus utilise cette approche pour rendre un DatePicker avec et sans accessoire className et garantit que le nom de classe "acme-datepicker" est en place dans les deux scénarios.

REMARQUE : Un didacticiel complet sur Testing Library est hors de portée de cet article, mais si vous voulez en savoir plus sur Testing Library, je vous recommande vivement de lire cette Introduction à Testing Library de Robin Wieruch .

] Pour exécuter ces nouveaux tests, retournez à votre terminal ou à l'invite de commande, puis exécutez à nouveau npm run test . Jest devrait trouver vos nouveaux tests automatiquement et ils devraient tous les deux réussir.

REMARQUE:

  • Si vous obtenez un Impossible de trouver module 'react' vous devez exécuter npm install react react-dom pour installer React en tant que dépendance de votre bibliothèque.
  • Si vous obtenez des avertissements de licence KendoReact et que vous souhaitez les supprimer, vous devrez ajouter la clé de licence KendoReact à votre dossier src .

À ce stade, vous disposez d'une configuration de test complète pour vos composants. Lorsque vous écrivez de nouveaux composants et que vous souhaitez les tester, il vous suffit de créer un nouveau fichier ComponentName.test.js . votre entreprise ou organisation. Cela ne nous laisse qu’un dernier sujet: déterminer comment documenter vos composants pour que d’autres connaissent comment les utiliser.

Comment documenter vos composants

La documentation est importante pour tout ensemble de composants réutilisables, car les développeurs doivent comprendre comment installer et utiliser vos composants, sinon ils ne commenceront jamais à construire quoi que ce soit .

La manière exacte dont vous documentez vos composants dépend parfois des politiques et de l'infrastructure de votre entreprise, mais dans cette section, je vais vous expliquer deux implémentations de documentation qui ont fonctionné pour moi et que vous devez prendre en compte.

Option de documentation n ° 1: Transformez votre application de démonstration en documentation

L'environnement de développement que nous avons créé tout au long de cette série d'articles comprend une application de démonstration complète pour tester vos composants dans une application réelle. L'avantage de cette application de démonstration est qu'il ne s'agit que d'une application Web, donc rien ne vous empêche de transformer votre application de démonstration en documentation de vos composants, puis de déployer cette application de démonstration quelque part dans votre organisation.

Pour vous donner un petit aperçu exemple de ce qui est possible, ouvrez votre fichier demo / src / App.js et remplacez son contenu par le code suivant.

 import  React  from   'react'  ];
 importation  DatePicker  de   'acme-components / DatePicker' ;

 import   'acme-components / theme.css' ;

 fonction  App () {
   retour  (
    <>

DatePicker

Utilisation par défaut

 {`
 importation  DatePicker  de   'acme-components / DatePicker' ;

`}

Définition d'une valeur par défaut

 {`
 importation  DatePicker  de   'acme-components / DatePicker' ;
<DatePicker defaultValue = { nouveau  Date ( 2022  0  1 )} />
`}

<DatePicker defaultValue = { nouveau Date ( 2022 0 1 )} />

L'ACME DatePicker est construit sur top de le KendoReact DatePicker, et vous pouvez <a href = " https://www.telerik.com/kendo-react-ui/components/dateinputs/datepicker/"[19459004[19459004)>refer à documentation de KendoReact pour propriétés supplémentaires qui vous pouvez pour personnalisation.


);
}

export default App;

Ensuite, retournez à votre terminal ou à l'invite de commande et accédez à votre répertoire demo (si vous n'y êtes pas déjà).

   cd   ../ démo

Et puis utilisez npm run start pour exécuter votre application de démonstration avec ces modifications.

 npm  run   start 

Vous devriez voir une interface utilisateur qui ressemble à ceci.

Voici une documentation de base qui montre aux autres développeurs comment fonctionne votre composant DatePicker. Vous pouvez également afficher les instructions d'installation, les bonnes pratiques , des directives de conception – ou vraiment, tout ce que vous voulez.

Et ceci est juste une implémentation très basique pour vous donner une idée de ce qui est possible. La plupart des sites de documentation comme celui-ci créent une page par composant, ainsi que des moyens pour naviguer entre les composants (onglets, tiroir, etc.).

Quelle que soit la façon dont vous choisissez d'écrire la documentation, il y a un gros avantage à traiter votre application de démonstration comme de la documentation: vous êtes obligé de mettre à jour la documentation lorsque vous mettez à jour les composants eux-mêmes – ce qui à mon avis est meilleur er than putting that same documentation on something like a wiki that you’ll constantly forget to update.

Let’s look at one additional option you have for documentation that builds on these same principles.

Documentation Option #2: Use Storybook

Storybook is an open-source tool that provides a number of tools for building component documentation. The Storybook approach is similar to what we discussed in the previous section—the difference being: Storybook makes building the documentation site itself super easy.

If you want to try it out, return to your terminal or command prompt, make sure you’re still in your demo directory, and run the following command to install Storybook.

npx sb init

This command takes a while to run, as Storybook is building a new stories folder in your demo/src directory, complete with sample documentation to help teach you how Storybook works.

To try it, you can next run npm run storybookand then visit http://localhost:6006 in your web browser. You should see something like this.

Default Storybook look. Navigation on the left. Main window shows 'Welcome to Storybook' and includes some options below Configure and Learn.

To get a sense of how Storybook works, create a new stories/DatePicker.js file and paste in the following code.

import React from 'react';
import DatePicker from 'acme-components/DatePicker';
import 'acme-components/theme.css';

export default {
  title: 'Example/DatePicker',
  component: DatePicker,
};

export const Default = () => 
export const Disabled = () => 

This file creates two “stories,” or ways of using your DatePicker component—one for the default usage of the DatePicker, and one for a DatePicker when it’s disabled.

After you save this change, you can return to http://localhost:6006 to see these new stories in a live app.

Storybook in action. DatePicker in Default allows you to click on the calendar icon and choose a date. In Disabled, the icon is grayed out.

The idea behind Storybook is you have a place to test all of your stories, or ways of using your components, and you could then distribute this Storybook to other developers so they can also learn how your components work.

Plus, I’m just showing the basics here. Storybook has an entire section of its site devoted to building documentation sitesmy favorite part being Storybook’s integration with MDXwhich is an interesting technology that lets you write JSX in Markdown documents.

Overall, Storybook is definitely a project that’s worth checking out as an option for documenting components for your company.

Wrapping up

Phew, it’s been quite a ride. If you’ve finished this whole article series, you’ve learned how to plan out a component library, how to set up a full development environment, and—in this article—how to build, test and document your components.

Even though I’ve tried to cover most common topics and questions, building component libraries is challenging and complex. With that in mind, if any questions came up while reading through this series, feel free to reach out in the comments, or to me personally on Twitter (@tjvantoll). And best of luck building your library! 😃

NOTE: The full source code for this article series is available on GitHub—feel free to use that as a reference, or as a starting point for your own component library.






Source link

0 Partages