版本：3.5.2

Docusaurus 用戶端 API

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 元件時可能發生的用戶端轉譯錯誤。

屬性

fallback：一個可選的轉譯回呼，會傳回 JSX 元素。它會接收一個具有 2 個屬性的物件：error（已捕捉到的錯誤）和 tryAgain（一個函數（() => void）回呼，用於重設元件中的錯誤並嘗試再次轉譯）。如果不存在，則會改為轉譯 @theme/Error。@theme/Error 用於包裝佈局上方網站的錯誤邊界。

警告

fallback 屬性是一個回呼，而不是 React 函數元件。您無法在此回呼中使用 React hook。

`<Head/>`

這個可重複使用的 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>

`<Link/>`

此元件可以連結到內部頁面，並提供稱為預載的強大效能功能。預載用於預先擷取資源，以便在使用者使用此元件導航時擷取資源。我們使用 IntersectionObserver 在 <Link> 位於檢視區時擷取低優先順序的請求，然後在使用者可能導航至所請求的資源時使用 onMouseOver 事件觸發高優先順序的請求。

此元件是 react-router 的 <Link> 元件的包裝器，它新增了 Docusaurus 特有的實用增強功能。所有屬性都會傳遞給 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" />

提示

建議使用此元件，而不是普通的 <a> 標籤，因為如果您使用 <Link>，Docusaurus 會進行許多優化（例如，損壞路徑偵測、預先擷取、套用基本 URL...）。

`<Redirect/>`

轉譯 <Redirect> 將會導航到新的位置。新的位置將會像伺服器端重新導向 (HTTP 3xx) 一樣覆蓋歷程堆疊中的目前位置。您可以參閱 React Router 的 Redirect 文件以取得有關可用屬性的更多資訊。

使用範例

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

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

注意

@docusaurus/router 實作了 React Router 並支援其功能。

`<BrowserOnly/>`

<BrowserOnly> 元件允許在 React 應用程式完成 hydration 後，僅在瀏覽器中轉譯 React 元件。

提示

將其用於與無法在 Node.js 中執行的程式碼整合，因為正在存取 window 或 document 物件。

屬性

children：傳回僅限瀏覽器的 JSX 的轉譯函數屬性。不會在 Node.js 中執行
fallback（可選）：要在伺服器 (Node.js) 上轉譯的 JSX，直到 React hydration 完成為止。

使用程式碼的範例

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 元素（字串、連結、樣式化元素...）。

屬性

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.dev.org.tw" className="my-website-class">
            website
          </Link>
        ),
      }}>
      {'Hello, {firstName}! How are you? Take a look at my {website}'}
    </Interpolate>
  );
}

`<Translate/>`

在將您的網站本地化時，<Translate/> 元件將允許為 React 元件提供翻譯支援，例如您的首頁。<Translate> 元件支援插值。

翻譯字串將使用 docusaurus write-translations CLI 從您的程式碼中靜態擷取，並在 website/i18n/[locale] 中建立 code.json 翻譯檔案。

注意

<Translate/> 屬性必須是硬編碼的字串。

除了用於插值的 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>
  );
}

注意

您甚至可以省略 children 屬性，並在執行 docusaurus write-translations CLI 命令後，手動在 code.json 檔案中指定翻譯字串。

<Translate id="homepage.title" />

資訊

<Translate> 元件支援插值。您也可以透過一些自訂程式碼和 translate 命令式 API 來實作字串複數化。

Hook

`useDocusaurusContext`

用於存取 Docusaurus Context 的 React hook。context 包含 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 應用程式已在瀏覽器中成功完成 hydration 時傳回 true。

警告

在 React 轉譯邏輯中使用這個 hook，而不是 typeof windows !== 'undefined'。

第一個用戶端轉譯輸出（在瀏覽器中）必須與伺服器端轉譯輸出 (Node.js) 完全相同。如 hydration 的危險中所述，不遵守此規則可能會導致非預期的 hydration 行為。

使用範例

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

const MyComponent = () => {
  const isBrowser = useIsBrowser();
  return <div>{isBrowser ? 'Client' : 'Server'}</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" 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`

存取由特定外掛執行個體建立的全域資料。

這是存取外掛全域資料最方便的 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>;
};

`useBrokenLinks`

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> 元件的指令式對應項。

簽章

// 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，例如

頁面 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.dev.org.tw/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`

一個公開了一些布林變數的模組，用於檢查目前的轉譯環境。

警告

對於 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_ID`	`預設`

元件​

<ErrorBoundary />​

屬性​

<Head/>​

<Link/>​

to：字串​

<Redirect/>​

<BrowserOnly/>​

屬性​

使用程式碼的範例​

使用程式庫的範例​

<Interpolate/>​

屬性​

<Translate/>​

屬性​

範例​

Hook​

useDocusaurusContext​

useIsBrowser​

useBaseUrl​

選項​

範例用法：​

useBaseUrlUtils​

useGlobalData​

usePluginData​

useAllPluginInstancesData​

useBrokenLinks​

函式​

interpolate​

簽章​

範例​

translate​

簽章​

範例​

模組​

ExecutionEnvironment​

constants​

元件

`<ErrorBoundary />`

屬性

`<Head/>`

`<Link/>`

`to`：字串

`<Redirect/>`

`<BrowserOnly/>`

屬性

使用程式碼的範例

使用程式庫的範例

`<Interpolate/>`

屬性

`<Translate/>`

屬性

範例

Hook

`useDocusaurusContext`

`useIsBrowser`

`useBaseUrl`

選項

範例用法：

`useBaseUrlUtils`

`useGlobalData`

`usePluginData`

`useAllPluginInstancesData`

`useBrokenLinks`

函式

`interpolate`

簽章

範例

`translate`

簽章

範例

模組

`ExecutionEnvironment`

`constants`