API client Docusaurus
Docusaurus fournit quelques API sur les clients qui peuvent vous être utiles lors de la construction de votre site.
Composants
<ErrorBoundary />
Ce composant crée une Limite d'erreur de React.
Utilisez-le pour envelopper les composants susceptibles de se bloquer, et affichez une solution de repli lorsque cela se produit au lieu de faire planter toute l'application.
import React from 'react';
import ErrorBoundary from '@docusaurus/ErrorBoundary';
const SafeComponent = () => (
<ErrorBoundary
fallback={({error, tryAgain}) => (
<div>
<p>Ce composant s'est planté à cause d'une erreur : {error.message}.</p>
<button onClick={tryAgain}>Réessayez !</button>
</div>
)}>
<SomeDangerousComponentThatMayThrow />
</ErrorBoundary>
);
Pour le voir en action, cliquez ici :
Docusaurus utilise ce composant pour détecter les erreurs dans la mise en page du thème, mais aussi dans l'ensemble de l'application.
Ce composant ne détecte pas les erreurs de construction et protège uniquement contre les erreurs de rendu côté client qui peuvent survenir lors de l'utilisation de composants d'état de React.
Props
fallback
: un callback optionnel de rendu renvoyant un élément JSX. Il recevra un objet avec 2 attributs :error
, l'erreur qui a été détectée, ettryAgain
, une fonction (() = void
) de rappel pour réinitialiser l'erreur dans le composant et essayer de le rendre à nouveau. S'il n'est pas présent,@theme/Error
sera rendu à la place.@theme/Error
est utilisé pour les limites d'erreur qui enveloppent le site, au-dessus de la mise en page.
La prop fallback
est une callback, et n'est pas un composant fonctionnel React. Vous ne pouvez pas utiliser les hooks React à l'intérieur de ce callback.
<Head/>
Ce composant React réutilisable gérera toutes les modifications apportées à la tête (« Head ») du document. Il prend des balises HTML simples et affiche des balises HTML simples et est facile à utiliser pour les débutants. C'est une enveloppe autour de React Helmet.
Exemple d'utilisation :
import React from 'react';
import Head from '@docusaurus/Head';
const MySEO = () => (
<Head>
<meta property="og:description" content="My custom description" />
<meta charSet="utf-8" />
<title>My Title</title>
<link rel="canonical" href="http://mysite.com/example" />
</Head>
);
Les composants imbriqués ou les derniers remplaceront les utilisations dupliquées :
<Parent>
<Head>
<title>Mon Titre</title>
<meta name="description" content="Helmet application" />
</Head>
<Child>
<Head>
<title>Titre imbriqué</title>
<meta name="description" content="Composant imbriqué" />
</Head>
</Child>
</Parent>
Sorties :
<head>
<title>Titre imbriqué</title>
<meta name="description" content="Composant imbriqué" />
</head>
<Link/>
Ce composant permet de créer des liens vers des pages internes ainsi qu'une puissante fonctionnalité de performance appelée « préchargement ». Le préchargement est utilisé pour récupérer les ressources à l'avance, de sorte que les ressources soient récupérées au moment où l'utilisateur navigue avec ce composant. Nous utilisons un IntersectionObserver
pour récupérer une requête de faible priorité lorsque le <Link>
est dans le viewport, puis nous utilisons un événement onMouseOver
pour déclencher une requête de haute priorité lorsqu'il est probable qu'un utilisateur navigue vers la ressource demandée.
Ce composant est une enveloppe autour du composant <Link>
de react-router qui ajoute des améliorations utiles spécifiques à Docusaurus. Tous les props sont transmis au composant <Link>
de react-router.
Les liens externes fonctionnent également, et ont automatiquement ces props : target="_blank" rel="noopener noreferrer"
.
import React from 'react';
import Link from '@docusaurus/Link';
const Page = () => (
<div>
<p>
Check out my <Link to="/blog">blog</Link>!
</p>
<p>
Follow me on <Link to="https://x.com/docusaurus">X</Link>!
</p>
</div>
);
to
: string
L'emplacement cible vers lequel vous souhaitez naviguer. Exemple : /docs/introduction
.
<Link to="/courses" />
Préférez ce composant aux balises vanilla <a>
car Docusaurus fait beaucoup d'optimisations (par exemple, détection de chemins cassés, prélecture, application de l'URL de base...) si vous utilisez <Link>
.
<Redirect/>
Rendre un <Redirect>
permet de naviguer vers un nouvel emplacement. Le nouvel emplacement remplacera l'emplacement actuel de la pile d'historique comme le font les redirections côté serveur (HTTP 3xx). Vous pouvez consulter la documentation de React Router Redirect pour plus d'informations sur les props disponibles.
Exemple d'utilisation :
import React from 'react';
import {Redirect} from '@docusaurus/router';
const Home = () => {
return <Redirect to="/docs/test" />;
};
@docusaurus/router
implémente React Router et prend en charge ses fonctionnalités.
<BrowserOnly/>
Le composant <BrowserOnly>
permet de rendre les composants React uniquement dans le navigateur après que l'application React se soit hydratée.
Utilisez-le pour intégrer du code qui ne peut pas s'exécuter dans Node.js, parce que des objets window
ou document
sont accédés.
Props
children
: prop de fonction de rendu retournant le JSX du navigateur uniquement. Ne sera pas exécuté dans Node.jsfallback
(facultatif) : JSX à rendre sur le serveur (Node.js) et jusqu'à ce que l'hydratation React soit terminée.
Exemple avec du code
import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {
return (
<BrowserOnly>
{() => <span>page url = {window.location.href}</span>}
</BrowserOnly>
);
};
Exemple avec une bibliothèque
import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = (props) => {
return (
<BrowserOnly fallback={<div>Loading...</div>}>
{() => {
const LibComponent = require('some-lib').LibComponent;
return <LibComponent {...props} />;
}}
</BrowserOnly>
);
};
<Interpolate/>
Un composant d'interpolation simple pour le texte contenant des placeholders dynamiques.
Les placeholders seront remplacés par les valeurs dynamiques fournies et les éléments JSX de votre choix (chaînes, liens, éléments stylés...).
Props
children
: texte contenant des placeholders d'interpolation comme{placeholderName}
values
: objet contenant des valeurs placeholder d'interpolation
import React from 'react';
import Link from '@docusaurus/Link';
import Interpolate from '@docusaurus/Interpolate';
export default function VisitMyWebsiteMessage() {
return (
<Interpolate
values={{
firstName: 'Sébastien',
website: (
<Link to="https://docusaurus.io" className="my-website-class">
website
</Link>
),
}}>
{'Hello, {firstName} ! Comment allez-vous ? Jetez un coup d\'œil à mon {website}'}
</Interpolate>
);
}
<Translate/>
Lors de la localisation de votre site, le composant <Translate/>
permettra de fournir un support de traduction aux composants React, comme votre page d'accueil. Le composant <Translate>
prend en charge l'interpolation.
Les chaînes de traduction seront extraites statiquement de votre code avec la CLI docusaurus write-translations
et un fichier de traduction code.json
sera créé dans website/i18n/[locale]
.
Les props de <Translate/>
doivent être des chaînes codées en dur.
Mis à part la prop values
utilisée pour l'interpolation, il n'est pas possible d'utiliser des variables, sinon l'extraction statique ne fonctionnerait pas.
Props
children
: chaîne non traduite dans la locale par défaut du site (peut contenir des placeholders d'interpolation)id
: valeur optionnelle à utiliser comme clé dans les fichiers de traduction JSONdescription
: texte optionnel pour aider le traducteurvalues
: objet optionnel contenant des valeurs placeholder d'interpolation
Exemple
import React from 'react';
import Layout from '@theme/Layout';
import Translate from '@docusaurus/Translate';
export default function Home() {
return (
<Layout>
<h1>
<Translate
id="homepage.title"
description="Le message de bienvenue de la page d'accueil">
Bienvenue sur mon site web
</Translate>
</h1>
<main>
<Translate values={{firstName: 'Sébastien'}}>
{'Bienvenue, {firstName} ! Comment allez-vous ?'}
</Translate>
</main>
</Layout>
);
}
Vous pouvez même omettre la prop enfant et spécifier manuellement une chaîne de traduction dans votre fichier code.json
après avoir exécuté la commande CLI docusaurus write-translations
.
<Translate id="homepage.title" />
Le composant <Translate>
prend en charge l'interpolation. Vous pouvez également implémenter la pluralisation des chaînes par le biais d'un code personnalisé et de l'API impérative translate
.
Hooks
useDocusaurusContext
Hook de React pour accéder au contexte Docusaurus. Le contexte contient l'objet siteConfig
depuis docusaurus.config.js et quelques métadonnées supplémentaires du site.
type PluginVersionInformation =
| {readonly type: 'package'; readonly version?: string}
| {readonly type: 'project'}
| {readonly type: 'local'}
| {readonly type: 'synthetic'};
type SiteMetadata = {
readonly docusaurusVersion: string;
readonly siteVersion?: string;
readonly pluginVersions: Record<string, PluginVersionInformation>;
};
type I18nLocaleConfig = {
label: string;
direction: string;
};
type I18n = {
defaultLocale: string;
locales: [string, ...string[]];
currentLocale: string;
localeConfigs: Record<string, I18nLocaleConfig>;
};
type DocusaurusContext = {
siteConfig: DocusaurusConfig;
siteMetadata: SiteMetadata;
globalData: Record<string, unknown>;
i18n: I18n;
codeTranslations: Record<string, string>;
};
Exemple d'utilisation :
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const MyComponent = () => {
const {siteConfig, siteMetadata} = useDocusaurusContext();
return (
<div>
<h1>{siteConfig.title}</h1>
<div>{siteMetadata.siteVersion}</div>
<div>{siteMetadata.docusaurusVersion}</div>
</div>
);
};
L'objet siteConfig
ne contient que des valeurs sérialisables (valeurs qui sont préservées après JSON.stringify()
). Les fonctions, les regex, etc. seraient perdus du côté client.
useIsBrowser
Renvoie true
lorsque l'application React s'est hydratée avec succès dans le navigateur.
Utilisez ce hook au lieu de typeof windows !== 'undefined'
dans la logique de rendu de React.
Le premier rendu côté client (dans le navigateur) doit être exactement le même que le rendu côté serveur (Node.js). Ne pas suivre cette règle peut entraîner des comportements d'hydratation inattendus, comme décrit dans The Perils of Rehydration.
Exemple d'utilisation :
import React from 'react';
import useIsBrowser from '@docusaurus/useIsBrowser';
const MyComponent = () => {
const isBrowser = useIsBrowser();
return <div>{isBrowser ? 'Client' : 'Serveur'}</div>;
};
useBaseUrl
Hook de React pour préfixer le baseUrl
de votre site à une chaîne.
Ne l'utilisez pas pour les liens normaux !
Le préfixe /baseUrl/
est automatiquement ajouté à tous les chemins absolus par défaut :
- Markdown :
[link](/my/path)
sera lié à/baseUrl/my/path
- React :
<Link to="/my/path/">link</Link>
sera lié à/baseUrl/my/path
Options
type BaseUrlOptions = {
forcePrependBaseUrl: boolean;
absolute: boolean;
};
Exemple d'utilisation :
import React from 'react';
import useBaseUrl from '@docusaurus/useBaseUrl';
const SomeImage = () => {
const imgSrc = useBaseUrl('/img/myImage.png');
return <img src={imgSrc} />;
};
Dans la plupart des cas, vous n'avez pas besoin de useBaseUrl
.
Préférez un appel require()
pour les ressources :
<img src={require('@site/static/img/myImage.png').default} />
useBaseUrlUtils
Parfois, useBaseUrl
n'est pas suffisant. Ce hook retourne des utilitaires supplémentaires liés à l'URL de base de votre site.
withBaseUrl
: utile si vous avez besoin d'ajouter des URL de base à plusieurs URL à la fois.
import React from 'react';
import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
const Component = () => {
const urls = ['/a', '/b'];
const {withBaseUrl} = useBaseUrlUtils();
const urlsWithBaseUrl = urls.map(withBaseUrl);
return <div>{/* ... */}</div>;
};
useGlobalData
Hook de React pour accéder aux données globales de Docusaurus créées par tous les plugins.
Les données globales sont des espaces nommés par le nom du plugin et l'ID du plugin.
L'ID du plugin n'est utile que si un plugin est utilisé plusieurs fois sur le même site. Chaque instance de plugin est capable de créer ses propres données globales.
type GlobalData = Record<
PluginName,
Record<
PluginId, // "default" par défaut
any // données spécifiques au plugin
>
>;
Exemple d'utilisation :
import React from 'react';
import useGlobalData from '@docusaurus/useGlobalData';
const MyComponent = () => {
const globalData = useGlobalData();
const myPluginData = globalData['my-plugin']['default'];
return <div>{myPluginData.someAttribute}</div>;
};
Inspectez les données globales de votre site depuis .docusaurus/globalData.json
usePluginData
Accéder aux données globales créées par une instance spécifique du plugin.
C'est le hook le plus pratique pour accéder aux données globales du plugin et devrait être utilisé la plupart du temps.
pluginId
est facultatif si vous n'utilisez pas de plugins multi-instances.
function usePluginData(
pluginName: string,
pluginId?: string,
options?: {failfast?: boolean},
);
Exemple d'utilisation :
import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
const myPluginData = usePluginData('my-plugin');
return <div>{myPluginData.someAttribute}</div>;
};
useAllPluginInstancesData
Accéder aux données globales créées par un plugin spécifique. Donné un nom de plugin, il retourne les données de toutes les instances de plugins de ce nom, pour chaque id de plugin.
function useAllPluginInstancesData(
pluginName: string,
options?: {failfast?: boolean},
);
Exemple d'utilisation :
import React from 'react';
import {useAllPluginInstancesData} from '@docusaurus/useGlobalData';
const MyComponent = () => {
const allPluginInstancesData = useAllPluginInstancesData('my-plugin');
const myPluginData = allPluginInstancesData['default'];
return <div>{myPluginData.someAttribute}</div>;
};
useBrokenLinks
Un hook React pour accéder aux API du vérificateur de liens défectueux de Docusaurus, exposant un moyen pour une page Docusaurus de rapporter et de collecter ses liens et ses ancrages.
Il s'agit d'une interface avancée que la plupart des utilisateurs de Docusaurus n'ont pas besoin d'utiliser directement.
Il est déjà intégré dans les composants de haut niveau existants :
- le composant
<Link>
va collecter des liens pour vous - le
@theme/Heading
(utilisée pour les entêtes Markdown) va collecter les ancrages
Utilisez useBrokenLinks()
si vous implémentez votre propre composant <Heading>
ou <Link>
.
Exemple d'utilisation :
import useBrokenLinks from '@docusaurus/useBrokenLinks';
export default function MyHeading(props) {
useBrokenLinks().collectAnchor(props.id);
return <h2 {...props} />;
}
import useBrokenLinks from '@docusaurus/useBrokenLinks';
export default function MyLink(props) {
useBrokenLinks().collectLink(props.href);
return <a {...props} />;
}
Fonctions
interpolate
La contrepartie impérative du composant <Interpolate>
.
Signature
// Interpolation simple de chaîne de caractères
function interpolate(text: string, values: Record<string, string>): string;
// interpolation JSX
function interpolate(
text: string,
values: Record<string, ReactNode>,
): ReactNode;
Exemple
import {interpolate} from '@docusaurus/Interpolate';
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});
translate
La contrepartie impérative du composant <Translate>
. Elle prend en charge aussi l'interpolation des placeholders.
Utilisez l'API impérative pour les rares cas où un composant ne peut pas être utilisé, tels que :
- la métadonnée
title
de la page - les props
placeholder
pour des saisies de formulaire - les props
aria-label
pour l'accessibilité
Signature
function translate(
translation: {message: string; id?: string; description?: string},
values: Record<string, string>,
): string;
Exemple
import React from 'react';
import Layout from '@theme/Layout';
import {translate} from '@docusaurus/Translate';
export default function Home() {
return (
<Layout
title={translate({message: 'Titre méta de ma page'})}>
<img
src={'https://docusaurus.io/logo.png'}
aria-label={
translate(
{
message: 'Le logo du site {siteName}',
// Optionnel
id: 'homepage.logo.ariaLabel',
description: 'Libellé aria du logo de la page d\'accueil',
},
{siteName: 'Docusaurus'},
)
}
/>
</Layout>
);
}
Modules
ExecutionEnvironment
Un module qui expose quelques variables booléennes pour vérifier l'environnement de rendu actuel.
Pour la logique de rendu de React, utilisez useIsBrowser()
ou <BrowserOnly>
à la place.
Exemple :
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
if (ExecutionEnvironment.canUseDOM) {
require('lib-that-only-works-client-side');
}
Champ | Description |
---|---|
ExecutionEnvironment.canUseDOM | true si sur le client/navigateur, false si c'est Node.js/pré-rendu. |
ExecutionEnvironment.canUseEventListeners | true si sur le client et nous avons window.addEventListener . |
ExecutionEnvironment.canUseIntersectionObserver | true si sur le client et nous avons IntersectionObserver . |
ExecutionEnvironment.canUseViewport | true si sur le client et nous avons window.screen . |
constants
Un module exposant des constantes utiles au code du thème côté client.
import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
Export nommé | Valeur |
---|---|
DEFAULT_PLUGIN_ID | default |