# React

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

## 手順

{% stepper %}
{% step %}
**パッケージをインストールする**

追加する `@gitbook/embed` React プロジェクトに:

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

完全な API リファレンスとソースコードについては、 [`@gitbook/embed` の GitHub 上のパッケージを参照してください](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', '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`。これにより、アプリのテーマと自動的に一致させられます。
{% 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`            | いいえ | `{}`                    | フレームコンテナーに適用するインラインスタイル。  |
| `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 ツール。詳細は [カスタムツールの作成](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/creating-custom-tools.md) を参照してください。

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

### `visitor` (認証済みアクセス)

次の用途に使用 [Adaptive Content](/docs/documentation/ja-gitbook-documentation/saitoakusesu/adaptive-content.md) 、 [認証済みアクセス](/docs/documentation/ja-gitbook-documentation/saitoakusesu/authenticated-access.md).

* **入力します**: `{ 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 ではありません`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-site/embedding/implementation/react.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.