Docusaurus 客户端 API
Docusaurus 提供了一组客户端 API,对于构建网站很有帮助。
组件
<ErrorBoundary />
This component creates a React error boundary.
Use it to wrap components that might throw, and display a fallback when that happens instead of crashing the whole app.
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
To see it in action, click here:
info
Docusaurus uses this component to catch errors within the theme's layout, and also within the entire app.
note
This component doesn't catch build-time errors and only protects against client-side render errors that can happen when using stateful React components.
Props
fallback
: an optional callback returning a JSX element. It will receive two props:error
, the error that was caught, andtryAgain
, a function (() => void
) callback to reset the error in the component and try rendering it again.
<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>
组件。
可用于指向站外的链接,并且会被自动添加这些属性: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
:字符串类型
目标位置。例如: /docs/introduction
。
<Link to="/courses" />
tip
Prefer this component to vanilla <a>
tags because Docusaurus does a lot of optimizations (e.g. broken path detection, prefetching, applying base URL...) if you use <Link>
.
<Redirect/>
Rendering a <Redirect>
will navigate to a new location. The new location will override the current location in the history stack like server-side redirects (HTTP 3xx) do. You can refer to React Router's Redirect documentation for more info on available props.
用法示例:
import React from 'react';
import {Redirect} from '@docusaurus/router';
const Home = () => {
return <Redirect to="/docs/test" />;
};
note
@docusaurus/router
实现了 React Router 并支持同样功能。
<BrowserOnly/>
The <BrowserOnly>
component permits to render React components only in the browser after the React app has hydrated.
tip
Use it for integrating with code that can't run in Node.js, because the window
or document
objects are being accessed.
Props
children
: render function prop returning browser-only JSX. Will not be executed in Node.jsfallback
(optional): JSX to render on the server (Node.js) and until React hydration completes.
Example with code
import BrowserOnly from '@docusaurus/BrowserOnly';
const MyComponent = () => {
return (
<BrowserOnly>
{() => <span>page url = {window.location.href}</span>}
</BrowserOnly>
);
};
Example with a library
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 元素(字符串、链接、styled elements等)。
参数(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。
The translation strings will statically extracted from your code with the docusaurus write-translations
CLI and a code.json
translation file will be created in website/i18n/[locale]
.
note
<Translate/>
组件的参数(props)只能是硬编码的字符串。
Apart from the values
prop used for interpolation, it is not possible to use variables, or the static extraction wouldn't work.
参数(Props)
children
: untranslated string in the default site locale (can contain interpolation placeholders)id
: optional value to be used as the key in JSON translation filesdescription
: optional text to help the translatorvalues
: optional object containing interpolation placeholder values
示例
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
You can even omit the children prop and specify a translation string in your code.json
file manually after running the docusaurus write-translations
CLI command.
<Translate id="homepage.title" />
React 钩子(Hooks)
useDocusaurusContext
React hook to access Docusaurus Context. The context contains the siteConfig
object from docusaurus.config.js and some additional site metadata.
type PluginVersionInformation =
| {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, PluginVersionInformation>;
}
interface I18nLocaleConfig {
label: string;
direction: string;
}
interface I18n {
defaultLocale: string;
locales: [string, ...string[]];
currentLocale: string;
localeConfigs: Record<string, I18nLocaleConfig>;
}
interface DocusaurusContext {
siteConfig: DocusaurusConfig;
siteMetadata: DocusaurusSiteMetadata;
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
The siteConfig
object only contains serializable values (values that are preserved after JSON.stringify()
). Functions, regexes, etc. would be lost on the client side.
useIsBrowser
Returns true
when the React app has successfully hydrated in the browser.
caution
Use this hook instead of typeof windows !== 'undefined'
in React rendering logic.
The first client-side render output (in the browser) must be exactly the same as the server-side render output (Node.js). Not following this rule can lead to unexpected hydration behaviors, as described in The Perils of Rehydration.
Usage example:
import React from 'react';
import useIsBrowser from '@docusaurus/useIsBrowser';
const MyComponent = () => {
const isBrowser = useIsBrowser();
return <div>{isBrowser ? 'Client' : 'Server'}</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
: useful if you need to add base URLs to multiple URLs at once.
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)用于访问所有插件所创建的全局数据。
Global data is namespaced by plugin name then by plugin ID.
info
Plugin ID is only useful when a plugin is used multiple times on the same site. Each plugin instance is able to create its own global data.
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
访问由特定插件实例所创建的全局数据。
This is the most convenient hook to access plugin global data and should be used most of the time.
如果你没有使用插件的多个实例,则 pluginId
是可选的。
function 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;
示例
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
A module that exposes a few boolean variables to check the current rendering environment.
caution
For React rendering logic, use useIsBrowser()
or <BrowserOnly>
instead.
Example:
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';
Named export | Value |
---|---|
DEFAULT_PLUGIN_ID | default |