Version : 2.0.0-beta.21

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}>Essayez à nouveau !</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);

astuce

Pour le voir en action, cliquez ici :

info

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.

remarque

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, et tryAgain, 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/Erreur est utilisé pour les limites d'erreur qui enveloppent le site, au-dessus de la mise en page.

attention

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. Il s'agit d'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>Mon Titre</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="Nested component" />
</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>
      Consultez mon <Link to="/blog">blog</Link>!
    </p>
    <p>
      Suivez-moi sur <Link to="https://twitter.com/docusaurus">Twitter</Link>!
    </p>
  </div>
);

`to` : string

L'emplacement cible vers lequel vous souhaitez naviguer. Exemple : /docs/introduction.

<Link to="/courses" />

astuce

Préférez ce composant aux balises vanilla <a> car si vous utilisez <Link>, Docusaurus effectue de nombreuses optimisations (par exemple, la détection des chemins brisés, le prefetch, l'application de l'URL de base...).

`<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 vous référer à la documentation de redirection de React Router 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" />;
};

remarque

@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.

astuce

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.js
fallback (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 vas-tu ? Jete un œ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, tels que 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 créera un fichier de traduction code.json dans website/i18n/[locale].

remarque

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 JSON
description : texte optionnel pour aider le traducteur
values : objet optionnel contenant des valeurs placeholder d'interpolation

Exemple

src/pages/index.js
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="The homepage welcome message">
          Welcome to my website
        </Translate>
      </h1>
      <main>
        <Translate values={{firstName: 'Sébastien'}}>
          {'Welcome, {firstName}! How are you?'}
        </Translate>
      </main>
    </Layout>
  );
}

remarque

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" />

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>
  );
};

remarque

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.

attention

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 conduire à 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' : 'Server'}</div>;
};

`useBaseUrl`

Hook de React pour préfixer le baseUrl de votre site à une chaîne.

attention

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/">lien</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} />;
};

astuce

Dans la plupart des cas, vous n'avez pas besoin de useBaseUrl.

Préférez un appel de 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.

info

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>;
};

astuce

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>;
};

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.

astuce

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

src/pages/index.js
import React from 'react';
import Layout from '@theme/Layout';

import {translate} from '@docusaurus/Translate';

export default function Home() {
  return (
    <Layout
      title={translate({message: 'My page meta title'})}>
      <img
        src={'https://docusaurus.io/logo.png'}
        aria-label={
          translate(
            {
              message: 'The logo of site {siteName}',
              // Optional
              id: 'homepage.logo.ariaLabel',
              description: 'The home page logo aria label',
            },
            {siteName: 'Docusaurus'},
          )
        }
      />
    </Layout>
  );
}

Modules

`ExecutionEnvironment`

Un module qui expose quelques variables booléennes pour vérifier l'environnement de rendu actuel.

attention

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`

Composants​

<ErrorBoundary />​

Props​

<Head/>​

<Link/>​

to : string​

<Redirect/>​

<BrowserOnly/>​

Props​

Exemple avec du code​

Exemple avec une bibliothèque​

<Interpolate/>​

Props​

<Translate/>​

Props​

Exemple​

Hooks​

useDocusaurusContext​

useIsBrowser​

useBaseUrl​

Options​

Exemple d'utilisation:​

useBaseUrlUtils​

useGlobalData​

usePluginData​

useAllPluginInstancesData​

Fonctions​

interpolate​

Signature​

Exemple​

translate​

Signature​

Exemple​

Modules​

ExecutionEnvironment​

constants​

Composants

`<ErrorBoundary />`

Props

`<Head/>`

`<Link/>`

`to` : string

`<Redirect/>`

`<BrowserOnly/>`

Props

Exemple avec du code

Exemple avec une bibliothèque

`<Interpolate/>`

Props

`<Translate/>`

Props

Exemple

Hooks

`useDocusaurusContext`

`useIsBrowser`

`useBaseUrl`

Options

Exemple d'utilisation:

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

Fonctions

`interpolate`

Signature

Exemple

`translate`

Signature

Exemple

Modules

`ExecutionEnvironment`

`constants`