Docusaurus 客户端 API

优质

小牛编辑

131浏览

2023-12-01

Docusaurus 提供了一组客户端 API，对于构建网站很有帮助。

组件

`<Head/>`

这是一个可重用 React 组件，用于管理对 HTML 文档标头（即 <head> 中的标签）的修改。此组件接收纯 HTML 标签并输出纯 HTML 标签，对初学者很友好。此组件始对 React Helmet 的二次包装。

用法示例：

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

嵌套或靠后定义的组件将覆盖之前的定义：

<Parent>
  <Head>

<title>My Title</title> <meta name="description" content="Helmet application" /> </Head> <Child> <Head> <title>Nested Title</title> <meta name="description" content="Nested component" /> </Head> </Child></Parent>

输出为：

<head>
  <title>Nested Title</title>
  <meta name="description" content="Nested component" />
</head>

`<Link/>`

此组件让你可以链接站内页面并使用被称为预加载（preloading）的强大功能。预加载功能用于预取资源，以便在用户使用此组件切换页面时取回页面资源。我们利用 IntersectionObserver 检测到<Link> 处于视口（viewport）中时发起一个低优先级的资源请求，并且利用 onMouseOver 事件来发起一个高优先级的资源请求（因为这是用户的明确目的）。

此组件是对 react-router 的 <Link> 组件的二次包装，并添加了专门对 Docusaurus 的增强功能。所有传递过来的参数（props）都将透传给 react-router 的 <Link> 组件。

import React from 'react';
import Link from '@docusaurus/Link';

const Page = () => ( <div> <p> Check out my <Link to="/blog">blog</Link>! </p> <p> {/* 注意，站外链接仍然使用 `a` 标签，并且会自动打开新的浏览器页面加载该链接。 */} Follow me on <a href="https://twitter.com/docusaurus">Twitter</a>! </p> </div> );

`to`：字符串类型

目标位置。例如： /docs/introduction。

<Link to="/courses" />

`<Redirect/>`

<Redirect> 渲染之后用于导航到新位置。新位置将覆盖 history 记录栈中的当前位置，就像服务器端的重定向（即 HTTP 3xx）一样。你可以参考 React Router 中关于重定向的文档以了解有哪些参数（props）可以使用。

用法示例：

import React from 'react';
import {Redirect} from '@docusaurus/router';

const Home = () => { return <Redirect to="/docs/test" />;};

note

@docusaurus/router 实现了 React Router 并支持同样功能。

`<BrowserOnly/>`

<BrowserOnly> 组件接收一个 children 参数，该参数是一个渲染函数，在构建过程中的预渲染阶段并不会执行。这对于隐藏仅在浏览器中运行的代码将很有用（例如，在需要访问 window/document 对象的地方）。为了提升 SEO 效果，你还可以通过 fallback 参数来提供备用内容，该参数将在构建过程中被预先渲染，并在浏览器中显示时由客户端内容所替换。

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = () => { return ( <BrowserOnly fallback={<div>The fallback content to display on prerendering</div>}> {() => { // Something that should be excluded during build process prerendering. }} </BrowserOnly> ); };

`<Interpolate/>`

该组件用于对文本中所包含的占位符做替换。

占位符将被替换为动态值和你所选择的 JSX 元素（字符串、链接、styled elements等）。

参数

children：包含占位符（例如 {placeholderName}）的文本
values：包含占位符替换值的对象

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}! How are you? Take a look at my {website}'} </Interpolate> ); }

`<Translate/>`

当本地化你的网站时，<Translate/> 组件将用于 为 React 组件提供对翻译功能的支持，例如翻译你的主页。<Translate> 组件支持 interpolation。

待翻译的字符串将被 docusaurus write-translations 命令从你的代码中提取出来，并在 website/i18n/<locale> 位置创建一个 code.json 文件用于翻译。

note

<Translate/> 组件的参数（props）只能是硬编码的字符串。

除了用于 interpolation 的 values 参数（prop）外，不能使用变量，否则无法提取待翻译的字符串。

参数（Props）

children：网站的默认 locale 中未经翻译的字符串（可以包含用于被替换的占位符）
id：可选值，在 JSON 文件（保存待翻译的字符串）中作为键（key）使用
description：可选值，用于为译者提供帮助性的信息
values: 可选值，该对象包含用于替换占位符的值

示例

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

React 钩子（Hooks）

`useDocusaurusContext`

用于访问 Docusaurus 核心数据的 React 钩子（hook）。核心数据包含来自 docusaurus.config.js 中的 siteConfig 对象，以及一些其它的站点元数据信息。

type DocusaurusPluginVersionInformation =
  | {readonly type: 'package'; readonly version?: string}
  | {readonly type: 'project'}
  | {readonly type: 'local'}
  | {readonly type: 'synthetic'};
interface DocusaurusSiteMetadata {
  readonly docusaurusVersion: string;
  readonly siteVersion?: string;
  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
}
interface DocusaurusContext {
  siteConfig: DocusaurusConfig;
  siteMetadata: DocusaurusSiteMetadata;
}

用法示例：

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

`useBaseUrl`

此 React 钩子（hook）用于将网站的 baseUrl 添加到某个字符串前面。

caution

请勿将其用于普通链接！

默认情况下，/baseUrl/ 前缀会被自动添加到所有 绝对路径 前面：

Markdown：[link](/my/path) 将连接到 /baseUrl/my/path
React: <Link to="/my/path/">link</Link> 将连接到 /baseUrl/my/path

参数

type BaseUrlOptions = {
  forcePrependBaseUrl: boolean;
  absolute: boolean;
};

用法示例：

import React from 'react';
import useBaseUrl from '@docusaurus/useBaseUrl';
const SomeImage = () => {
  const imgSrc = useBaseUrl('/img/myImage.png');

return <img src={imgSrc} />; };

tip

在大多数情况下，你并不需要使用 useBaseUrl。

针对静态资源的引用，推荐使用 require()：

<img src={require('@site/static/img/myImage.png').default} />

`useBaseUrlUtils`

有时，useBaseUrl 还不够好用。而 useBaseUrlUtils 能够返回一组额外的与网站的 baseUrl 相关的辅助函数。

withBaseUrl：如果你需要一次性将 baseUrl 添加到多个网址，那么这个函数就很有用了。

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`

此 React 钩子（hook）用于访问所有插件所创建的全局数据。

全局数据是采用插件名和插件 id 作为命名空间的。

info

当一个站点上使用某个插件的多个实例时，插件 id 才有用。每个插件实例都可以创建自己的全局数据。

type GlobalData = Record<
  PluginName,
  Record<
    PluginId, // 默认值是 "default"
    any // 特定于插件的数据
  >
>;

用法示例：

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

tip

通过 ./docusaurus/globalData.json 文件可以查看站点的全局数据

`usePluginData`

访问由特定插件实例所创建的全局数据。

这是一个访问插件的全局数据的最方便的 React 钩子（hook），大部分情况下都应该使用它。

如果你没有使用插件的多个实例，则 pluginId 是可选的。

usePluginData(pluginName: string, pluginId?: string)

用法示例：

import React from 'react';
import {usePluginData} from '@docusaurus/useGlobalData';

const MyComponent = () => { const myPluginData = usePluginData('my-plugin'); return <div>{myPluginData.someAttribute}</div>;};

`useAllPluginInstancesData`

访问由特定插件所创建的全局数据。给定插件名称后，该函数将返回以该名称命名的所有插件实例的全局数据，并按照插件 id 标记数据。

useAllPluginInstancesData(pluginName: string)

用法示例：

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

函数

`interpolate`

对应 <Interpolate> 组件的具有相同功能的函数。

用法

// 简单的字符串替换
function interpolate(text: string, values: Record<string, string>): string;
// JSX interpolation
function interpolate(
  text: string,
  values: Record<string, ReactNode>,
): ReactNode;

示例

import {interpolate} from '@docusaurus/Interpolate';

const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});

`translate`

对应 <Translate> 组件的具有相同功能的函数。也支持占位符替换。

tip

对于 无法使用组件 的 罕见情况，请使用该函数，例如：

页面的 title 元数据
表单输入框的 placeholder 属性（props）
用于可访问性功能中的 aria-label 属性（props）

用法

function translate(
  translation: {message: string; id?: string; description?: string},
  values: Record<string, string>,
): string;

示例

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}', // 可选 id: 'homepage.logo.ariaLabel', description: 'The home page logo aria label', }, {siteName: 'Docusaurus'}, ) } /> </Layout> ); }

模块

`ExecutionEnvironment`

该模块用于暴露一些用于检查当前渲染环境的布尔值变量。如果只想在客户端或服务器端上运行某些代码，或者需要编写兼容服务器端渲染的代码，则会很有用。

import React from 'react';
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

const MyPage = () => { const location = ExecutionEnvironment.canUseDOM ? window.location.href : null; return <div>{location}</div>; };

变量	描述
`ExecutionEnvironment.canUseDOM`	如果在客户端，则为 `true`；如果是预渲染，则为 `false`。
`ExecutionEnvironment.canUseEventListeners`	如果在客户端并且定义了 `window.addEventListener`，则为`true`
`ExecutionEnvironment.canUseIntersectionObserver`	如果在客户端并且定义了 `IntersectionObserver`，则为 `true`。
`ExecutionEnvironment.canUseViewport`	如果在客户端并且定义了 `window.screen`，则为`true`。

`constants`

该模块用于为客户端的主题代码暴露一些有用的常量。

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';

Named export	Value
`DEFAULT_PLUGIN_ID`	`default`

Docusaurus 客户端 API

组件

<Head/>

<Link/>

to：字符串类型

<Redirect/>

note

<BrowserOnly/>

<Interpolate/>

参数

<Translate/>

note

参数（Props）

示例

React 钩子（Hooks）

useDocusaurusContext

useBaseUrl

caution

参数

用法示例：

tip

useBaseUrlUtils

useGlobalData

info

tip

usePluginData

useAllPluginInstancesData

函数

interpolate

用法

示例

translate

tip

用法

示例

模块

ExecutionEnvironment

constants

`<Head/>`

`<Link/>`

`to`：字符串类型

`<Redirect/>`

`<BrowserOnly/>`

`<Interpolate/>`

`<Translate/>`

`useDocusaurusContext`

`useBaseUrl`

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

`interpolate`

`translate`

`ExecutionEnvironment`

`constants`