メインコンテンツへスキップ
バージョン: 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 と、コンポーネントのエラーをリセットして再度レンダリングを試みるための関数 (() => void) コールバックである tryAgain です。存在しない場合は、代わりに @theme/Error がレンダリングされます。 @theme/Error は、レイアウトの上にあるサイトをラップするエラー境界に使用されます。
警告

fallback プロパティはコールバックであり、React の関数型コンポーネントではありません。このコールバック内で React フックを使用することはできません。

この再利用可能な React コンポーネントは、ドキュメントの 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> がビューポートにある場合は低優先度のリクエストをフェッチするために IntersectionObserver を使用し、ユーザーが要求されたリソースに移動する可能性が高い場合は高優先度のリクエストをトリガーするために onMouseOver イベントを使用します。

このコンポーネントは、Docusaurus 固有の便利な拡張機能を追加する react-router の <Link> コンポーネントのラッパーです。すべてのプロパティは、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" />
ヒント

Docusaurus は、<Link> を使用すると、多くの最適化 (例: 壊れたパスの検出、プリフェッチ、ベース URL の適用など) を行うため、通常の <a> タグよりもこのコンポーネントを優先してください。

<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 アプリがハイドレーションされた後、ブラウザーでのみ React コンポーネントをレンダリングできます。

ヒント

window オブジェクトまたは document オブジェクトにアクセスしているため、Node.js で実行できないコードと統合する場合に使用します。

プロパティ​

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

<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.dokyumento.jp" 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>
  );
}
注意

docusaurus write-translations CLI コマンドを実行した後、children プロパティを省略して、code.json ファイルに翻訳文字列を手動で指定することもできます。

<Translate id="homepage.title" />
情報

<Translate> コンポーネントは補間をサポートしています。文字列の複数形化を、いくつかのカスタムコードとtranslate 命令型 API を使用して実装することもできます。

フック​

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

siteConfig オブジェクトには、シリアル化可能な値 (JSON.stringify() 後も保持される値) のみが含まれています。関数、正規表現などはクライアント側で失われます。

useIsBrowser​

React アプリがブラウザーで正常にハイドレーションされたときに true を返します。

警告

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​

サイトの baseUrl を文字列に付加する React フック。

警告

通常のリンクには使用しないでください!

/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() の呼び出しを推奨します。

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

すべてのプラグインによって作成された Docusaurus グローバルデータにアクセスするための React フック。

グローバルデータは、プラグイン名、次にプラグイン 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>;
};

Docusaurus の壊れたリンクチェッカー API にアクセスするための React フック。Docusaurus ページがリンクとアンカーを報告および収集する方法を公開します。

警告

これは、**ほとんどの Docusaurus ユーザーが直接使用する必要がない** **高度な** API です。

既存の高度なコンポーネントにすでに**組み込まれて**います。

  • <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.dokyumento.jp/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_IDdefault