版本：Canary 🚧

文档龙客户端接口

Docusaurus 在客户端上提供了一些 api，可以帮助您构建站点。

组件

`<ErrorBoundary />`

这个组件创建了一个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>
);

提示

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

信息

Docusaurus 使用这个组件来捕捉主题布局中的错误，以及整个应用程序中的错误。

备注

该组件不捕获构建时错误，只防止使用有状态 React 组件时可能发生的客户端呈现错误。

Props

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

警告

fallback prop 是一个回调，而不是一个 React 的功能组件。你不能在这个回调中使用 React 钩子。

`<Head/>`

这个可重用的 React 组件将管理对文档头部的所有更改。它接受纯 HTML 标记并输出纯 HTML 标记，对初学者很友好。它是一个包装React 头盔。

使用的例子:

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

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

该组件是 react-router 的<Link>组件的包装器，该组件为 Docusaurus 添加了有用的增强功能。所有的 props 都被传递给 react-router 的<Link>组件。

外部链接也可以工作，并自动具有这些属性: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://twitter.com/docusaurus">Twitter</Link>!
    </p>
  </div>
);

`to`: string

要导航到的目标位置。例子: /docs/introduction.

<Link to="/courses" />

提示

比起普通的<a>标签，我更喜欢这个组件，因为如果你使用<Link>，Docusaurus 会做很多优化(例如路径检测，预取，应用基础 URL…)。

`<Redirect/>`

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

使用示例:

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

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

备注

@docusaurus/router实现了React 路由器并支持它的特性。

`<BrowserOnly/>`

<BrowserOnly>组件只允许在 React 应用完成后在浏览器中渲染 React 组件。

提示

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

Props

children: 渲染函数 prop 返回仅浏览器的 JSX。不会在 Node.js 中执行
fallback (可选): 在服务器(Node.js)上渲染 JSX，直到 React 的水合作用完成。

代码示例

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

`<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">
            website
          </Link>
        ),
      }}
    >
      {"Hello, {firstName}! How are you? Take a look at my {website}"}
    </Interpolate>
  );
}

`<Translate/>`

当本地化你的站点时，<Translate/>组件将允许为 React 组件提供翻译支持，比如你的主页。<Translate>组件支持interpolation。

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

备注

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

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

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">
          Welcome to my website
        </Translate>
      </h1>
      <main>
        <Translate values={{ firstName: "Sébastien" }}>{"Welcome, {firstName}! How are you?"}</Translate>
      </main>
    </Layout>
  );
}

备注

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

<Translate id="homepage.title" />

信息

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

钩子

`useDocusaurusContext`

React 钩子访问 Docusaurus 上下文。上下文包含来自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 渲染逻辑中使用这个钩子代替typeof windows !== 'undefined'。

第一个客户端呈现输出(在浏览器中)必须与服务器端呈现输出(Node.js)完全相同。不遵循这一规则可能会导致意想不到的水合行为，正如补液的危险所描述的那样。

使用的例子:

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

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

`useBaseUrl`

React 钩子将你的站点baseUrl前缀为字符串。

警告

不要将它用于常规链接!

默认情况下，/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} />;
};

提示

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

建议使用 require()调用assets:

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

`useBaseUrlUtils`

有时useBaseUrl不够好。此钩子返回与站点基础 URL 相关的附加 utils。

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 钩子来访问 Docusaurus 所有插件创建的全局数据。

全局数据由插件名和插件 ID 命名。

信息

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

提示

检查您的网站的全局数据在./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>;
};

函数

`interpolate`

<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`

<Translate>组件的命令式对应。也支持占位符插值。

提示

在组件不能使用的情况下使用命令式 API，比如:

the page title metadata
the placeholder props of form inputs
the aria-label props for accessibility

Signature

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

Example

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`

一个公开几个布尔变量以检查当前呈现环境的模块。

警告

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

例子:

import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";

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

Field	描述
`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`

文档龙客户端接口

组件​

<ErrorBoundary />​

Props​

<Head/>​

<Link/>​

to: string​

<Redirect/>​

<BrowserOnly/>​

Props​

代码示例​

带有库的示例​

<Interpolate/>​

Props​

<Translate/>​

Props​

例子​

钩子​

useDocusaurusContext​

useIsBrowser​

useBaseUrl​

选项​

使用示例:​

useBaseUrlUtils​

useGlobalData​

usePluginData​

useAllPluginInstancesData​

函数​

interpolate​

签名​

例子​

translate​

Signature​

Example​

模块​

ExecutionEnvironment​

constants​

组件

`<ErrorBoundary />`

Props

`<Head/>`

`<Link/>`

`to`: string

`<Redirect/>`

`<BrowserOnly/>`

Props

代码示例

带有库的示例

`<Interpolate/>`

Props

`<Translate/>`

Props

例子

钩子

`useDocusaurusContext`

`useIsBrowser`

`useBaseUrl`

选项

使用示例:

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

函数

`interpolate`

签名

例子

`translate`

Signature

Example

模块

`ExecutionEnvironment`

`constants`