API client Docusaurus
Docusaurus fournit quelques API sur les clients qui peuvent vous être utiles lors de la construction de votre site.
#
Composants<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 :
Les composants imbriqués ou les derniers remplaceront les utilisations dupliquées :
Sorties :
<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.
to
: string#
L'emplacement cible vers lequel vous souhaitez naviguer. Exemple : /docs/introduction
.
<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:
remarque
@docusaurus/router
implémente React Router et prend en charge ses fonctionnalités.
<BrowserOnly/>
#
Le composant <BrowserOnly>
accepte une prop children
, une fonction de rendu qui ne sera pas exécutée pendant la phase de pré-rendu du processus de compilation. Ceci est utile pour cacher le code qui n'est destiné qu'à s'exécuter dans les navigateurs (par exemple, là où l'on accède aux objets window
/document
). Pour améliorer le référencement, vous pouvez également fournir un contenu de repli en utilisant le prop fallback
, qui sera prérendu jusqu'au processus de construction et remplacé par le contenu côté client uniquement lors de l'affichage dans le navigateur.
<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...).
#
Propschildren
: texte contenant des placeholders d'interpolation comme{placeholderName}
values
: objet contenant des valeurs placeholder d'interpolation
<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 de votre code avec le 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.
#
Propschildren
: 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#
HooksuseDocusaurusContext
#
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.
Exemple d'utilisation :
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#
Exemple d'utilisation:astuce
Dans la plupart des cas, vous n'avez pas besoin de useBaseUrl
.
Préférez un appel de require()
pour les ressources :
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.
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.
Exemple d'utilisation :
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.
Exemple d'utilisation :
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.
Exemple d'utilisation :
#
Fonctionsinterpolate
#
La contrepartie impérative du composant <Interpolate>
.
#
Signature#
Exempletranslate
#
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#
Exemple#
ModulesExecutionEnvironment
#
Un module qui expose quelques variables booléennes pour vérifier l'environnement de rendu actuel. Utile si vous voulez n'exécuter que du code sur le client/serveur ou si vous avez besoin d'écrire du code compatible avec le rendu côté serveur.
Champ | Description |
---|---|
ExecutionEnvironment.canUseDOM | true si sur le client, false si c'est le 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.
Export nommé | Valeur |
---|---|
DEFAULT_PLUGIN_ID | default |