React

事前構築されたReactコンポーネントを使ってReactアプリにDocs Embedを追加する

Reactプロジェクト向けに、GitBookはドキュメントを埋め込むことを簡単かつ慣習的に行える事前構築コンポーネントを提供します。これらのコンポーネントは状態管理、コンテキスト、およびライフサイクルを自動的に処理します。

手順

1

パッケージをインストール

追加 @gitbook/embed あなたのReactプロジェクトに：

npm install @gitbook/embed

完全なAPIリファレンスとソースコードについては、次を参照してください： @gitbook/embed GitHub上のパッケージ.

2

Reactコンポーネントをインポートする

をインポートします GitBookProvider および GitBookFrame components:

import {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";

3

アプリをGitBookProviderでラップする

プロバイダーをコンポーネントツリーのルート、または埋め込みが必要な場所に追加します：

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <YourAppContent />
    </GitBookProvider>
  );
}

4

GitBookFrameコンポーネントを追加する

埋め込みを表示したい場所にフレームコンポーネントを配置します：

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <div className="app">
        <YourAppContent />
        <GitBookFrame
          visitor={{
            token: 'your-jwt-token', // 任意: Adaptive Content または認証アクセス用
            unsignedClaims: { userId: '123' } // オプション：動的式のためのカスタムクレーム
          }}
        />
      </div>
    </GitBookProvider>
  );
}

5

埋め込みをカスタマイズする

フレームコンポーネントに設定プロップを渡します：

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    tabs={['assistant', 'docs']}
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    suggestions={['What is GitBook?', 'How do I get started?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

6

useGitBookフックで埋め込みを制御する

を使用して useGitBook フックでプログラム的に埋め込みと対話します：

import { useGitBook } from "@gitbook/embed/react";

function HelpButton() {
  const gitbook = useGitBook();
  const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
  
  const handleNavigate = () => {
    const iframe = document.createElement('iframe');
    iframe.src = frameURL;
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('How do I get started?');
  };

  return <button onClick={handleNavigate}>Get Help</button>;
}

7

条件付きで埋め込みをレンダリングする

必要なときだけ埋め込みを表示する：

function App() {
  const [showEmbed, setShowEmbed] = useState(false);

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>Get Help</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

8

Next.jsまたはサーバーサイドレンダリングでの使用

SSRの問題を避けるためにコンポーネントを動的インポートします：

import dynamic from "next/dynamic";

const GitBookProvider = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookProvider),
  { ssr: false }
);

const GitBookFrame = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookFrame),
  { ssr: false }
);

プロップと設定

GitBookProviderのプロップ：

プロップ	を入力してから	必須	デフォルト	説明
siteURL	string	はい	該当なし	あなたのGitBookドキュメントサイトのURL（例、 https://docs.company.com).
children	ReactNode	はい	該当なし	プロバイダー内でレンダリングする子コンポーネント。

GitBookFrameのプロップ：

すべての設定オプションはプロップとして <GitBookFrame>に渡すことができます。利用可能なオプションは以下の「Configuration」セクションを参照してください。

プロップ	を入力してから	必須	デフォルト	説明
className	string	いいえ	null	フレームコンテナに適用するCSSクラス名。
style	オブジェクト	いいえ	{}	フレームコンテナに適用するインラインスタイル。
visitor	オブジェクト	いいえ	{}	認証付きアクセスのオプション（下記参照）。

useGitBookフック：

を返します GitBookClient 次のメソッドを持つインスタンス：

• getFrameURL(options?: { visitor?: {...} }) → string - iframeのURLを取得する

• createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - フレームクライアントを作成する

フレームクライアントは次を提供します：

• navigateToPage(path: string) → void

• navigateToAssistant() → void

• postUserMessage(message: string) → void

• clearChat() → void

• configure(settings: {...}) → void

• on(event: string, listener: Function) → () => void

設定オプション

設定オプションは <GitBookFrame>:

tabs

表示するタブを上書きします。デフォルトはサイトの設定です。

• を入力してから: ('assistant' | 'docs')[]

actions

タブの横にサイドバー内でレンダリングされるカスタムアクションボタン。各アクションボタンはクリック時にコールバックをトリガーします。

注意: 以前は次の名前でした buttons。使用するには actions を推奨します。

• を入力してから: Array<{ icon: string, label: string, onClick: () => void }>

greeting

アシスタントタブに表示される歓迎メッセージ。

• を入力してから: { title: string, subtitle: string }

suggestions

アシスタントの歓迎画面に表示される推奨質問。

• を入力してから: string[]

tools

アシスタントを拡張するカスタムAIツール。詳細は カスタムツールの作成 を参照してください。

• を入力してから: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

visitor (認証付きアクセス)

に関する用途で使用されます Adaptive Content および 認証されたアクセス.

• を入力してから: { token?: string, unsignedClaims?: Record<string, unknown> }

よくある落とし穴

• GitBookProviderでラップしていない – オプションの GitBookFrame には親 GitBookProvider が必要です。

• 動的インポートなしでSSRと一緒に使用する – コンポーネントはブラウザAPIを使用するため、Next.jsや他のSSRフレームワークでは動的にインポートする必要があります。

• siteURLが公開されたドキュメントと一致しない – プロップがあなたの公開中のドキュメントサイトのURLと正確に一致していることを確認してください。 siteURL propがあなたの公開ドキュメントサイトのURLと正確に一致していることを確認してください。

• プロバイダー外でuseGitBookを呼び出す – オプションの useGitBook フックは、の子であるコンポーネント内で使用する必要があります GitBookProvider.

• ツリー内の複数のプロバイダー – 複数のインスタンスをネストすることは避けてください。コンテキストの競合を引き起こす可能性があります。 GitBookProvider 使用している古いコンポーネント名

• – コンポーネントは現在 です。以前の名前ではありません GitBookFrameではなく GitBookAssistantFrame.