跳到主要内容

客户端 API

道格龙（Docusaurus）在客户端上提供了一些 API，这些 API 在你构建网站时可能会很有帮助。

组件​

<ErrorBoundary />​

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

用它来包裹可能会抛出错误的组件，并在发生错误时显示一个 回退UI，而不是让整个应用崩溃。

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

const SafeComponent = () => (
  <ErrorBoundary
    fallback={({error, tryAgain}) => (
      <div>
        <p>这个组件因为错误而崩溃了：{error.message}.</p>
        <button onClick={tryAgain}>再试一次!</button>
      </div>
    )}>
    <SomeDangerousComponentThatMayThrow />
  </ErrorBoundary>
);
提示

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

信息

道格龙（Docusaurus）使用此组件来捕获主题布局内部以及整个应用中的错误。

备注

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

Props​

  • fallback: 一个可选的渲染回调，返回一个 JSX 元素。它将接收一个包含 2 个属性的对象：error，即捕获到的错误；以及 tryAgain，一个用于重置组件中的错误并尝试再次渲染它的函数 (() => void) 回调。如果未提供，将改为渲染 @theme/Error。@theme/Error 用于包裹站点的错误边界，位于布局之上。
注意

fallback prop 是一个回调函数，而不是一个 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="我的自定义描述" />
    <meta charSet="utf-8" />
    <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 在 <Link> 进入视口时获取一个低优先级的请求，然后在用户很可能导航到所请求的资源时，使用一个 onMouseOver 事件来触发一个高优先级的请求。

该组件是 React Router 的 <Link> 组件的包装器，添加了针对道格龙（Docusaurus）的有用增强功能。所有 props 都会传递给 React Router 的 <Link> 组件。

外部链接也可以工作，并自动具有这些 props：target="_blank" rel="noopener noreferrer"。

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

const Page = () => (
  <div>
    <p>
      查看我的<Link to="/blog">博客</Link>！
    </p>
    <p>
      在 <Link to="https://x.com/docusaurus">X</Link> 上关注我！
    </p>
  </div>
);

to: string​

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

<Link to="/courses" />
提示

推荐使用此组件而不是普通的 <a> 标签，因为如果你使用 <Link>，道格龙（Docusaurus）会进行许多优化（例如，损坏路径检测、预取、应用基础 URL 等）。

<Redirect/>​

渲染一个 <Redirect> 将会导航到一个新位置。新位置将像服务器端重定向（HTTP 3xx）一样，在历史堆栈中覆盖当前位置。你可以参考 React Router 的 Redirect 文档了解更多关于可用 props 的信息。

使用示例：

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

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

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

<BrowserOnly/>​

<BrowserOnly> 组件允许仅在浏览器中、在 React 应用水合（hydrated）后渲染 React 组件。

提示

当你需要集成那些无法在 Node.js 中运行的代码时（因为它们访问了 window 或 document 对象），请使用此组件。

属性（Props）​

  • children: 一个渲染函数 prop，返回仅限浏览器的 JSX。它不会在 Node.js 中执行。
  • fallback (可选的): 在服务器端（Node.js）以及 React 水合完成前要渲染的 JSX。

代码示例​

import BrowserOnly from '@docusaurus/BrowserOnly';

const MyComponent = () => {
  return (
    <BrowserOnly>
      {() => <span>页面 URL = {window.location.href}</span>}
    </BrowserOnly>
  );
};

库使用示例​

import BrowserOnly from '@docusaurus/BrowserOnly';

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

<Interpolate/>​

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

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

属性（Props）​

  • 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">
            网站
          </Link>
        ),
      }}>
      {'你好, {firstName}! 你好吗？快来看看我的{website}'}
    </Interpolate>
  );
}

<Translate/>​

在本地化你的网站时，<Translate/> 组件将允许为 React 组件（例如你的主页）提供翻译支持。<Translate> 组件支持插值。

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

备注

<Translate/> 的 props 必须是硬编码的字符串。

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

属性（Props）​

  • 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">
          欢迎来到我的网站
        </Translate>
      </h1>
      <main>
        <Translate values={{firstName: 'Sébastien'}}>
          {'欢迎, {firstName}! 你好吗？'}
        </Translate>
      </main>
    </Layout>
  );
}
备注

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

<Translate id="homepage.title" />
信息

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

Hooks​

useDocusaurusContext​

用于访问道格龙（Docusaurus）上下文的 React hook。该上下文包含来自 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>
  );
};
备注

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

useIsBrowser​

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

注意

在 React 渲染逻辑中，请使用此 hook 而不是 typeof windows !== 'undefined'。

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

使用示例：

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

const MyComponent = () => {
  const isBrowser = useIsBrowser();
  return <div>{isBrowser ? '客户端' : '服务器'}</div>;
};

useBaseUrl​

一个 React hook，用于在一个字符串前加上你网站的 baseUrl。

注意

不要将其用于常规链接！

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

  • Markdown: [链接](/my/path) 将链接到 /baseUrl/my/path
  • React: <Link to="/my/path/">链接</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} />;
};
提示

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

对于资源请求，推荐使用 require() 调用：

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

useBaseUrlUtils​

有时 useBaseUrl 不够用。此 hook 返回与你网站的基础 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 进行命名空间划分。

信息

插件 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>;
};
提示

在 .docusaurus/globalData.json 中检查你站点的全局数据。

usePluginData​

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

这是访问插件全局数据最方便的 hook，应该在大多数时候使用。

如果你不使用多实例插件，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>;
};

一个 React hook，用于访问道格龙（Docusaurus）的损坏链接检查器 API，提供一种让道格龙（Docusaurus）页面报告和收集其链接和锚点的方式。

注意

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

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

  • <Link> 组件将为你收集链接
  • @theme/Heading（用于 Markdown 标题）将为你收集锚点

如果你实现自己的 <Heading> 或 <Link> 组件，请使用 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​

<Interpolate> 组件的命令式对应部分。

签名​

// 简单字符串插值
function interpolate(text: string, values: Record<string, string>): string;

// JSX 插值
function interpolate(
  text: string,
  values: Record<string, ReactNode>,
): ReactNode;

示例​

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

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

translate​

<Translate> 组件的命令式对应部分。同样支持占位符插值。

提示

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

  • 页面的 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: '我的页面元标题'})}>
      <img
        src={'https://docusaurus.io/logo.png'}
        aria-label={
          translate(
            {
              message: '网站 {siteName} 的 logo',
              // 可选
              id: 'homepage.logo.ariaLabel',
              description: 'The home page logo aria label',
            },
            {siteName: 'Docusaurus'},
          )
        }
      />
    </Layout>
  );
}

模块​

ExecutionEnvironment​

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

注意

对于 React 渲染逻辑，请改用 useIsBrowser() 或 <BrowserOnly>。

示例：

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  require('lib-that-only-works-client-side');
}
字段描述
ExecutionEnvironment.canUseDOM如果在客户端/浏览器中则为 true，在 Node.js/预渲染中则为 false。
ExecutionEnvironment.canUseEventListeners如果在客户端且有 window.addEventListener 则为 true。
ExecutionEnvironment.canUseIntersectionObserver如果在客户端且有 IntersectionObserver 则为 true。
ExecutionEnvironment.canUseViewport如果在客户端且有 window.screen 则为 true。

constants​

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

import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
命名导出值
DEFAULT_PLUGIN_IDdefault