Aller au contenu principal
Version : Canary 🚧

Swizzling

Dans cette section, nous présenterons comment la personnalisation de la mise en page se fait dans Docusaurus.

Déja vu... ?

Cette section est similaire au Style et mise en page, mais cette fois, nous allons écrire du code React concret au lieu de jouer avec des feuilles de style. Nous parlerons d'un concept central dans Docusaurus : le swizzling, qui permet des personnalisations plus profondes du site.

En pratique, le swizzling permet d'échanger un composant de thème avec votre propre implémentation, et il se décline en 2 modèles :

  • Éjection : crée une copie du composant du thème original, que vous pouvez entièrement personnaliser
  • Enveloppement : crée une enveloppe autour du composant du thème d'origine, que vous pouvez améliorer
Pourquoi l'appelle-t-on swizzling ?

Le nom vient de l'Objective-C et Swift-UI : la méthode de swizzling est le processus de modification de l'implémentation d'un sélecteur existant (méthode).

Pour Docusaurus, le « swizzling de composant » signifie fournir un composant alternatif qui a la priorité sur le composant fourni par le thème.

Vous pouvez l'imaginer comme une Modification de singe pour les composants React, vous permettant de remplacer l'implémentation par défaut. Gatsby a un concept similaire appelé ombrage de thème.

Pour mieux comprendre cela, vous devez comprendre comment les composants du thème sont résolus.

Processus du swizzling​

Vue d'ensemble​

Docusaurus fournit un CLI interactif pratique pour swizzler les composants. Généralement, vous n'avez qu'à vous souvenir de la commande suivante :

npm run swizzle

Il générera un nouveau composant dans votre répertoire src/theme, qui devrait ressembler à cet exemple :

src/theme/SomeComponent.js
import React from 'react';

export default function SomeComponent(props) {
  // Vous pouvez entièrement personnaliser cette implémentation
  // y compris changer le JSX, les hooks CSS et React
  return (
    <div className="some-class">
      <h1>Un composant</h1>
      <p>Quelques détails sur l'implémentation du composant</p>
    </div>
  );
}

Pour obtenir un aperçu de tous les thèmes et composants disponibles à swizzler, exécutez :

npm run swizzle -- --list

Utilisez --help pour voir toutes les options CLI disponibles, ou reportez-vous à la référence documentation du CLI de swizzle.

remarque

Après avoir swizzlé un composant, redémarrez votre serveur de développement pour que Docusaurus soit au courant du nouveau composant.

Privilégiez la sécurité

Assurez-vous de comprendre quels composants sont sûrs à swizzler. Certains composants sont des détails d'implémentation internes d'un thème.

info

docusaurus swizzle n'est qu'un moyen automatisé pour vous aider à swizzler le composant. Vous pouvez également créer le fichier src/theme/SomeComponent.js manuellement, et Docusaurus le résoudra. Il n'y a pas de magie interne derrière cette commande !

Éjection​

L'éjection d'un composant de thème est le processus de création d'une copie du composant de thème d'origine, que vous pouvez entièrement personnaliser et remplacer.

Pour éjecter un composant de thème, utilisez le swizzle du CLI de manière interactive, ou avec l'option --eject :

npm run swizzle [nom du thème] [nom du composant] -- --eject

Un exemple :

npm run swizzle @docusaurus/theme-classic Footer -- --eject

Ceci copiera l'implémentation du composant <Footer /> actuel dans le répertoire src/theme de votre site. Docusaurus utilisera maintenant cette copie de composant <Footer> au lieu de l'originale. Vous êtes maintenant libre de réimplémenter complètement le composant <Footer>.

src/theme/SomeComponent.js
import React from 'react';

export default function Footer(props) {
  return (
    <footer>
      <h1>C'est le pied de page de mon site personnalisé</h1>.
      <p>Et il est très différent de l'original</p>.
    </footer>
  );
}
attention

L'éjection d'un composant non sûr peut parfois conduire à copier une grande quantité de code interne, que vous devez maintenant maintenir vous-même. Cela peut rendre les mises à jour de Docusaurus plus difficiles, car vous devrez migrer vos personnalisations si les props reçus ou les API de thème internes utilisées ont changé.

Préférez l'enveloppement chaque fois que c'est possible : la quantité de code à maintenir est plus petite.

Le re-swizzling

Pour garder les composants éjectés à jour après une mise à niveau de Docusaurus, exécutez à nouveau la commande eject et comparez les changements avec git diff. Il est également recommandé d'écrire un bref commentaire en haut du fichier expliquant les modifications que vous avez apportées, afin de pouvoir plus facilement réappliquer vos modifications après la ré-éjection.

Enveloppement​

L'enveloppement d'un composant de thème est le processus de création d'une enveloppe autour du composant du thème original, que vous pouvez améliorer.

Pour envelopper un composant de thème, utilisez le CLI swizzle de manière interactive, ou avec l'option --wrap :

npm run swizzle [theme name] [component name] -- --wrap

Un exemple :

npm run swizzle @docusaurus/theme-classic Footer -- --wrap

Cela créera une enveloppe dans le répertoire src/theme de votre site. Docusaurus utilisera désormais le composant <FooterWrapper> au lieu du composant original. Vous pouvez maintenant ajouter des personnalisations autour du composant original.

src/theme/SomeComponent.js
import React from 'react';
import Footer from '@theme-original/Footer';

export default function FooterWrapper(props) {
  return (
    <>
      <section>
        <h2>Section supplémentaire</h2>
        <p>Ceci est une section supplémentaire qui apparaît au-dessus du pied de page</p>
      </section>
      <Footer {...props} />
    </>
  );
}
C'est quoi ce @theme-original ?

Docusaurus utilise les alias de thème pour résoudre les composants du thème à utiliser. L'enveloppe nouvellement créé prend l'alias @theme/SomeComponent. @theme-original/SomeComponent permet d'importer le composant original que l'enveloppe masque sans créer une boucle d'importation infinie dans laquelle l'enveloppe s'importe elle-même.

astuce

L'enveloppement d'un thème est un excellent moyen d'ajouter des composants supplémentaires autour d'un existant sans l'éjection. Par exemple, vous pouvez facilement ajouter un système de commentaires personnalisés sous chaque article du blog :

src/theme/BlogPostItem.js
import React from 'react';
import BlogPostItem from '@theme-original/BlogPostItem';
import MyCustomCommentSystem from '@site/src/MyCustomCommentSystem';

export default function BlogPostItemWrapper(props) {
  return (
    <>
      <BlogPostItem {...props} />
      <MyCustomCommentSystem />
    </>
  );
}

Qu'est-ce qui est sans danger pour swizzler ?​

Un grand pouvoir implique de grandes responsabilités

Certains composants de thème sont des détails d'implémentation internes d'un thème. Docusaurus vous permet de les swizzler, mais cela peut être risqué.

Pourquoi c'est risqué ?

Les auteurs de thèmes (dont nous faisons partie) peuvent être amenés à mettre à jour leur thème au fil du temps : changement des composants, de leur nom, de l'emplacement du système de fichiers, des types... Par exemple, considérons un composant qui reçoit deux props name et age, mais après une refactorisation, il reçoit maintenant une prop person avec les deux propriétés ci-dessus. Votre composant, qui attend toujours ces deux props, rendra undefined à la place.

Par ailleurs, les composants internes peuvent tout simplement disparaître. Si un composant est appelé Sidebar et qu'il est plus tard renommé en DocSidebar, votre composant swizzlé sera complètement ignoré.

Les composants du thème marqués comme non sûrs peuvent être modifiés d'une manière incompatible avec les précédentes versions mineures du thème. Lors de la mise à jour d'un thème (ou de Docusaurus), vos personnalisations peuvent se comporter de manière inattendue, et peuvent même casser votre site.

Pour chaque composant de thème, le CLI de swizzle indiquera 3 niveaux de sécurité différents déclarés par les auteurs du thème :

  • Safe (sécurisé) : ce composant est sans danger pour être swizzlé, son API publique est considérée comme stable, et aucun changement ne devrait se produire dans version majeure du thème
  • Unsafe (non sûr) : ce composant est un détail de l'implémentation du thème, il n'est pas sûr pour le swizzling, et des changements peuvent survenir dans une version mineure d'un thème.
  • Forbidden (interdit): le CLI swizzle vous empêchera de swizzler ce composant, car il n'est pas conçu pour être swizzlé
remarque

Certains composants peuvent être sûrs pour l'enveloppement, mais pas pour l'éjection.

info

Ne soyez pas trop effrayé par l'utilisation de composants non sécurisés : gardez simplement à l'esprit que des modifications radicales peuvent survenir, et que vous devrez peut-être mettre à jour vos personnalisations manuellement lors des mises à jour mineures de version.

Signalez votre cas d'utilisation

Si vous avez un cas d'utilisation sérieux pour swizzler un composant non sûr, veuillez le signaler ici et nous travaillerons ensemble pour trouver une solution pour le rendre sûr.

Quel composant devrais-je swizzler ?​

Il n'est pas toujours facile de savoir quel est le composant à utiliser pour atteindre le résultat souhaité. @docusaurus/theme-classic, qui fournit la plupart des composants de thème, a environ 100 composants !

astuce

Pour lister un aperçu de tous les composants @docusaurus/theme-classic :

npm run swizzle @docusaurus/theme-classic -- --list

Vous pouvez suivre ces étapes pour localiser le composant approprié à swizzler :

  1. Description du composant. Certains composants fournissent une courte description, ce qui est un bon moyen de trouver le bon.
  2. Nom du composant. Les composants du thème officiel sont nommés de manière sémantique, vous devriez donc pouvoir déduire sa fonction à partir de son nom. La commande Swizzle du CLI vous permet de saisir une partie du nom d'un composant pour restreindre les choix disponibles. Par exemple, si vous exécutez yarn swizzle @docusaurus/theme-classic, et saisissez Doc, seuls les composants liés aux docs seront listés.
  3. Démarrer avec un composant de niveau supérieur. Les composants forment une arborescence, certains composants en important d'autres. Chaque route sera associée à un composant de premier niveau que la route rendra (la plupart d'entre elles sont listées dans Routage dans les plugins de contenu). Par exemple, toutes les pages de publication du blog ont @theme/BlogPostPage en tant que composant principal. Vous pouvez commencer par swizzler ce composant, puis descendre dans l'arborescence des composants pour trouver le composant qui rend exactement ce que vous ciblez. N'oubliez pas de déswizzler le reste en supprimant les fichiers après avoir trouvé le bon, afin de ne pas conserver trop de composants.
  4. Lisez le code source du thème et utilisez la recherche à bon escient.
Il vous suffit de demander !

Si vous n'avez toujours pas la moindre idée du composant à swizzler pour obtenir l'effet désiré, vous pouvez demander de l'aide à l'un de nos canaux de support.

Nous souhaitons également mieux comprendre vos cas d'utilisation de personnalisation les plus fantaisistes, alors n'hésitez pas à les reporter.

Ai-je besoin de swizzler ?​

Le swizzling signifie en fin de compte que vous devez maintenir du code React supplémentaire qui interagit avec les API internes de Docusaurus. Si vous le pouvez, pensez aux alternatives suivantes lors de la personnalisation de votre site :

  1. Utiliser le CSS. Les règles et les sélecteurs CSS peuvent souvent vous aider à atteindre un degré décent de personnalisation. Reportez-vous au style et la mise en page pour plus de détails.
  2. Utiliser des traductions. Cela peut sembler surprenant, mais les traductions ne sont en fin de compte qu'un moyen de personnaliser les libellés de texte. Par exemple, si la langue par défaut de votre site est en, vous pouvez toujours exécuter yarn write-translations -l en et modifier le code .json émis. Reportez-vous au tutoriel i18n pour plus de détails.
astuce

Plus c'est petit, mieux c'est. Si le swizzling est inévitable, préférez ne swizzler que la partie pertinente et maintenez par vous-même le moins de code possible. Le changement d'un petit composant signifie souvent moins de risque de modifications cassantes lors de la mise à niveau.

L'enveloppement est aussi une alternative bien plus sûre que l'éjection.

Enveloppez votre site avec <Root>​

Le composant <Root> est rendu tout en haut de l'arborescence React, au-dessus du thème <Layout>, et ne se démonte jamais. It is the perfect place to add stateful logic that should not be re-initialized across navigations (user authentication status, shopping cart state...).

Swizzlez-le manuellement en créant un fichier src/theme/Root.js :

src/theme/Root.js
import React from 'react';

// Implémentation par défaut, que vous pouvez personnaliser
export default function Root({children}) {
  return <>{children}</>;
}
astuce

Utilisez ce composant pour afficher les fournisseurs de contexte de React.