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

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

フレームコンポーネントに設定用の props を渡します:

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'search', 'docs']}
    colorScheme="dark"
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    assistantName="Support Copilot"
    closeButton={true}
    suggestions={['GitBook とは何ですか?', 'どうやって始めればよいですか?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'サポートに問い合わせる',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

を省略すると colorScheme、埋め込みは iframe の CSS に従います color-scheme。これにより、アプリのテーマと自動的に一致させられます。

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('どうやって始めればよいですか?');
  };

  return <button onClick={handleNavigate}>ヘルプを取得</button>;
}

7

条件付きで埋め込みを表示する

必要なときだけ埋め込みを表示します:

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

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>ヘルプを取得</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 }
);

Props と設定

GitBookProvider の props:

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

GitBookFrame の props:

すべての設定オプションは、次のコンポーネントの props として渡せます <GitBookFrame>。利用可能なオプションについては、以下の「設定」セクションを参照してください。

Prop	入力します	必須	デフォルト	説明
className	string	いいえ	null	フレームコンテナーに適用する CSS クラス名。
style	object	いいえ	{}	フレームコンテナーに適用するインラインスタイル。
colorScheme	'light' | 'dark'	いいえ	CSS から継承 color-scheme	に渡されます。埋め込みの配色を上書きします。
assistantName	string	いいえ	null	UI に表示されるアシスタント名を上書きします。
closeButton	boolean	いいえ	null	Assistant 内に閉じるボタンを表示します。
visitor	object	いいえ	{}	認証済みアクセスのオプション（下記参照）。

useGitBook フック:

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

• getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) → 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

設定オプション

設定オプションは、次のコンポーネントの props として利用できます <GitBookFrame>:

tabs

で利用できます。表示するタブを上書きします。

検索はデフォルトで有効です。 tabsを設定すると、埋め込みにはリストしたタブのみが表示されます。

• 入力します: ('assistant' | 'search' | 'docs')[]

colorScheme

に渡されます。埋め込みの配色を上書きします。

省略した場合、埋め込みは iframe の CSS color-schemeに従い、親ページまたはブラウザの設定を継承できます。

• 入力します: 'light' | 'dark'

を設定すると

タブと並んでサイドバーに表示されるカスタムアクションボタンです。各アクションボタンはクリック時にコールバックを実行します。

注: 以前はこれは buttonsという名前でした。 を設定すると の代わりに行うことをおすすめします。

• 入力します: Array<{ icon: string, label: string, onClick: () => void }>

greeting

Assistant タブに表示されるウェルカムメッセージ。

• 入力します: { title: string, subtitle: string }

assistantName

UI に表示されるアシスタント名を上書きします。

• 入力します: string

• 最大長: 32 文字

closeButton

Assistant 内に閉じるボタンを表示します。

• 入力します: boolean

suggestions

Assistant のウェルカム画面に表示されるおすすめの質問。

• 入力します: string[]

trademark

埋め込み UI で GitBook の商標を表示または非表示にします。これには Docs Embed のフッターと Assistant のブランド表示が含まれます。

• 入力します: boolean

• デフォルト: true

tools

Assistant を拡張するカスタム 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 が公開済みドキュメントと一致しない – siteURL prop が実際のドキュメントサイトの URL と完全に一致していることを確認してください。

• provider の外で useGitBook を呼び出す – useGitBook フックは、次のコンポーネントの子であるコンポーネント内で使用する必要があります GitBookProvider.

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

• 古いコンポーネント名を使う – 現在のコンポーネント名は GitBookFrameであり、 GitBookAssistantFrame ではありません.