Version: 3.7.0

Docusaurus 客户端 API

Docusaurus 在客户端提供了一些 API，这些 API 在构建您的网站时可能对您有所帮助。

组件

该组件创建了一个React错误边界。

使用它来包裹可能会抛出错误的组件，并在发生错误时显示一个备用界面，而不是导致整个应用程序崩溃。

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

const SafeComponent = () => (
  <ErrorBoundary
    fallback={({error, tryAgain}) => (
      <div>
        <p>This component crashed because of error: {error.message}.</p>
        <button onClick={tryAgain}>Try Again!</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);

tip

要查看它的实际效果，请点击这里：

info

Docusaurus 使用此组件来捕获主题布局内以及整个应用程序中的错误。

note

此组件不会捕获构建时错误，仅在使用有状态的React组件时防止客户端渲染错误。

属性

fallback: 一个可选的渲染回调函数，返回一个JSX元素。它将接收一个包含2个属性的对象：error，捕获的错误，和tryAgain，一个函数（() => void）回调，用于重置组件中的错误并尝试再次渲染。如果不存在，将渲染@theme/Error。@theme/Error用于包裹站点的错误边界，位于布局之上。

warning

fallback 属性是一个回调函数，而不是一个 React 函数组件。你不能在这个回调函数中使用 React hooks。

这个可重用的React组件将管理您对文档头部的所有更改。它接受普通的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>

该组件支持链接到内部页面以及一个强大的性能特性，称为预加载。预加载用于预取资源，以便在用户使用此组件导航时资源已被获取。我们使用IntersectionObserver在进入视口时获取低优先级请求，然后使用onMouseOver事件在用户可能导航到请求的资源时触发高优先级请求。

该组件是对 react-router 的组件的封装，增加了特定于 Docusaurus 的有用增强功能。所有属性都传递给 react-router 的组件。

外部链接也有效，并且自动具有这些属性：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`: 字符串

要导航到的目标位置。示例：/docs/introduction。

<Link to="/courses" />

tip

比起普通的标签，更推荐使用这个组件，因为如果你使用，Docusaurus会进行很多优化（例如，检测错误的路径、预取、应用基础URL等）。

渲染一个将会导航到一个新的位置。新位置将覆盖历史堆栈中的当前位置，就像服务器端重定向（HTTP 3xx）所做的那样。您可以参考React Router的Redirect文档以获取有关可用属性的更多信息。

示例用法：

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

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

note

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

组件允许在 React 应用程序水合后仅在浏览器中渲染 React 组件。

tip

用于与无法在Node.js中运行的代码集成，因为正在访问window或document对象。

属性

children: 渲染函数属性，返回仅限浏览器的JSX。不会在Node.js中执行
fallback（可选）：在服务器（Node.js）上渲染并在 React 水合完成之前显示的 JSX。

代码示例

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = () => {
  return (
    <BrowserOnly>
      {() => <span>page url = {window.location.href}</span>}
    </BrowserOnly>
  );
};

使用库的示例

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = (props) => {
  return (
    <BrowserOnly fallback={<div>Loading...</div>}>
      {() => {
        const LibComponent = require('some-lib').LibComponent;
        return <LibComponent {...props} />;
      }}
    </BrowserOnly>
  );
};

一个简单的插值组件，用于包含动态占位符的文本。

占位符将被替换为您提供的动态值和选择的JSX元素（字符串、链接、样式化元素...）。

属性

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

当本地化您的网站时，组件将允许为React组件提供翻译支持，例如您的主页。组件支持插值。

翻译字符串将从您的代码中静态提取，使用docusaurus write-translations CLI，并在website/i18n/[locale]中创建一个code.json翻译文件。

note

的属性 必须是硬编码的字符串。

除了用于插值的 values 属性外，不能使用变量，否则静态提取将无法工作。

属性

children: 默认站点语言环境中未翻译的字符串（可以包含插值占位符）
id: 可选值，用作JSON翻译文件中的键
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>
  );
}

note

你甚至可以省略children属性，并在运行docusaurus write-translations CLI命令后，手动在code.json文件中指定翻译字符串。

<Translate id="homepage.title" />

info

组件支持插值。你也可以通过一些自定义代码和 translate 命令式 API 实现字符串复数化。

Hooks

`useDocusaurusContext`

用于访问Docusaurus上下文的React钩子。上下文包含来自docusaurus.config.js的siteConfig对象和一些额外的站点元数据。

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

使用示例：

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

note

siteConfig 对象仅包含可序列化的值（在 JSON.stringify() 后保留的值）。函数、正则表达式等在客户端会丢失。

`useIsBrowser`

当React应用在浏览器中成功水合时返回true。

warning

在React渲染逻辑中使用此钩子代替typeof windows !== 'undefined'。

第一次客户端渲染输出（在浏览器中）必须与服务器端渲染输出（Node.js）完全相同。不遵循此规则可能会导致意外的水合行为，如The Perils of Rehydration中所述。

使用示例：

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

const MyComponent = () => {
  const isBrowser = useIsBrowser();
  return <div>{isBrowser ? 'Client' : 'Server'}</div>;
};

`useBaseUrl`

React hook 用于将您网站的 baseUrl 添加到字符串的前面。

warning

不要将其用于常规链接！

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

Markdown: [link](/my/path) 将链接到 /baseUrl/my/path
React: 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不够好。这个钩子返回与您站点基础URL相关的额外工具。

withBaseUrl: 如果你需要一次性为多个URL添加基础URL，这个功能会很有用。

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 用于访问由所有插件创建的 Docusaurus 全局数据。

全局数据按插件名称然后按插件ID进行命名空间。

info

插件ID仅在同一站点上多次使用插件时有用。每个插件实例都能够创建自己的全局数据。

type GlobalData = Record<
  PluginName,
  Record<
    PluginId, // "default" by default
    any // plugin-specific data
  >
>;

使用示例：

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`

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

这是访问插件全局数据最方便的钩子，大多数情况下应该使用它。

pluginId 是可选的，如果你不使用多实例插件。

function usePluginData(
  pluginName: string,
  pluginId?: string,
  options?: {failfast?: boolean},
);

使用示例：

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

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

`useAllPluginInstancesData`

访问由特定插件创建的全局数据。给定一个插件名称，它通过插件ID返回该名称的所有插件实例的数据。

function useAllPluginInstancesData(
  pluginName: string,
  options?: {failfast?: boolean},
);

使用示例：

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`

React hook 用于访问 Docusaurus 的坏链检查器 API，为 Docusaurus 页面提供了一种报告和收集其链接和锚点的方式。

warning

这是一个高级 API，大多数 Docusaurus 用户不需要直接使用。

它已经内置在现有的高级组件中：

组件将为您收集链接
@theme/Heading（用于 Markdown 标题）将收集锚点

如果您实现自己的或组件，请使用 useBrokenLinks()。

使用示例：

MyHeading.js
import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyHeading(props) {
  useBrokenLinks().collectAnchor(props.id);
  return <h2 {...props} />;
}

MyLink.js
import useBrokenLinks from '@docusaurus/useBrokenLinks';

export default function MyLink(props) {
  useBrokenLinks().collectLink(props.href);
  return <a {...props} />;
}

函数

`interpolate`

组件的命令式对应物。

签名

// Simple string interpolation
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`

组件的命令式对应物。还支持占位符插值。

tip

在极少数情况下，当无法使用组件时，使用命令式API，例如：

页面的title元数据
表单输入的placeholder属性
用于可访问性的aria-label属性

签名

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

模块

`ExecutionEnvironment`

一个模块，暴露了一些布尔变量来检查当前的渲染环境。

warning

对于React渲染逻辑，请使用useIsBrowser()或代替。

示例：

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  require('lib-that-only-works-client-side');
}

Field	Description
`ExecutionEnvironment.canUseDOM`	`true` if on client/browser, `false` on Node.js/prerendering.
`ExecutionEnvironment.canUseEventListeners`	`true` if on client and has `window.addEventListener`.
`ExecutionEnvironment.canUseIntersectionObserver`	`true` if on client and has `IntersectionObserver`.
`ExecutionEnvironment.canUseViewport`	`true` if on client and has `window.screen`.

`constants`

一个向客户端主题代码暴露有用常量的模块。

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

Named export	Value
`DEFAULT_PLUGIN_ID`	`default`

组件​

​

属性​

var _hmt = _hmt || []; (function() { var hm = document.createElement("script"); hm.src = "https://hm.baidu.com/hm.js?45fdf1e3ad7f1e5a16b9b8ce2dedd5ef"; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(hm, s); })(); ​

​

to: 字符串​

​

​

属性​

代码示例​

使用库的示例​

​

属性​

​

属性​

示例​

Hooks​

useDocusaurusContext​

useIsBrowser​

useBaseUrl​

选项​

示例用法：​

useBaseUrlUtils​

useGlobalData​

usePluginData​

useAllPluginInstancesData​

useBrokenLinks​

函数​

interpolate​

签名​

示例​

translate​

签名​

示例​

模块​

ExecutionEnvironment​

constants​

组件

属性

`to`: 字符串

属性

代码示例

使用库的示例

属性

属性

示例

Hooks

`useDocusaurusContext`

`useIsBrowser`

`useBaseUrl`

选项

示例用法：

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

`useBrokenLinks`

函数

`interpolate`

签名

示例

`translate`

签名

示例

模块

`ExecutionEnvironment`

`constants`