# React

React プロジェクトでは、GitBook は、ドキュメントの埋め込みをシンプルかつ自然にしてくれる事前構築済みコンポーネントを提供します。これらのコンポーネントは、状態管理、コンテキスト、ライフサイクルを自動的に処理します。

## 手順

{% stepper %}
{% step %}

#### パッケージをインストールする

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

```bash
npm install @gitbook/embed
```

完全な API リファレンスとソースコードについては、GitHub 上の次のものを参照してください： [`@gitbook/embed` パッケージ](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}

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

次をインポートします。 `GitBookProvider` 、 `GitBookFrame` components:

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

{% endstep %}

{% step %}

#### アプリを GitBookProvider でラップする

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

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

{% endstep %}

{% step %}

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

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

```jsx
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>
  );
}
```

{% endstep %}

{% step %}

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

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

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'docs']}
    greeting={{ title: 'ようこそ！', subtitle: 'どのようにお手伝いできますか？' }}
    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>
```

{% endstep %}

{% step %}

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

次の `useGitBook` フックを使って、埋め込みをプログラムから操作します：

```jsx
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>;
}
```

{% endstep %}

{% step %}

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

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

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

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>ヘルプを表示</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}
```

{% endstep %}

{% step %}

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

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

```jsx
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 }
);
```

{% endstep %}
{% endstepper %}

## 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` | いいえ | `{}`   | フレームコンテナーに適用するインラインスタイル。 |
| `visitor`   | `object` | いいえ | `{}`   | 認証済みアクセス用のオプション（以下を参照）。  |

**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`

## 設定オプション

設定オプションは、次の props として利用できます。 `<GitBookFrame>`:

### `tabs`

表示するタブを上書きします。既定値はサイトの設定です。

* **入力**: `('assistant' | 'docs')[]`

### `actions`

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

**注意**：以前はこれを `buttons`と呼んでいました。 `actions` の使用を検討してください。

* **入力**: `Array<{ icon: string, label: string, onClick: () => void }>`

### `greeting`

アシスタンタブに表示されるウェルカムメッセージ。

* **入力**: `{ title: string, subtitle: string }`

### `suggestions`

アシスタントのウェルカム画面に表示される提案質問。

* **入力**: `string[]`

### `trademark`

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

* **入力**: `boolean`
* **デフォルト**: `true`

### `tools`

アシスタントを拡張するためのカスタム AI ツールです。詳細は [カスタムツールの作成](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding/configuration/creating-custom-tools) をご覧ください。

* **入力**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>`

### `visitor` （認証済みアクセス）

用途： [Adaptive Content](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/adaptive-content) 、 [認証済みアクセス](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/authenticated-access).

* **入力**: `{ token?: string, unsignedClaims?: Record<string, unknown> }`

## よくある落とし穴

* **GitBookProvider でラップしない** – `GitBookFrame` 親が必要です `GitBookProvider` 動作するために。
* **動的インポートなしで SSR と併用する** – このコンポーネントはブラウザー API を使用するため、Next.js やその他の SSR フレームワークでは動的にインポートする必要があります。
* **siteURL が公開済みドキュメントと一致しない** – 次を確認してください。 `siteURL` prop が本番のドキュメントサイト URL と完全に一致していること。
* **プロバイダー外で useGitBook を呼び出す** – `useGitBook` フックは、次の子であるコンポーネント内で使用する必要があります。 `GitBookProvider`.
* **ツリー内に複数のプロバイダーがある** – 複数の `GitBookProvider` インスタンスをネストしないでください。コンテキストの競合を引き起こす可能性があります。
* **古いコンポーネント名を使う** – 現在のコンポーネント名は `GitBookFrame`であり、 `GitBookAssistantFrame ではありません`.