# General Translation Integrations: Recorder API
URL: https://generaltranslation.com/ja/docs/integrations/rrweb/reference/recorder.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: rrweb のイベントストリームとローカライズ済みテキストオーバーレイをキャプチャします。gt-rrweb レコーダーの API リファレンスです。

`gt-rrweb` から レコーダー の値をインポートします。録画には `react`、`react-dom`、`@rrweb/types` と、任意のピア依存関係である `@rrweb/record` が必要です。

## 概要 [#overview]

| API                                             | 説明                                      |
| ----------------------------------------------- | --------------------------------------- |
| [`GTRecorder`](#gt-recorder)                    | レコーダーの設定と録画オーバーレイをマウントします。              |
| [`GTRecorderProps`](#gt-recorder-props)         | `GTRecorder` が受け取る props。               |
| [`useRecorder`](#use-recorder)                  | モジュールレベルのレコーダーを開始・停止します。                |
| [`UseRecorder`](#use-recorder-result)           | `useRecorder` が返すレコーダーのコントロールと現在のステータス。 |
| [`RecordingOverlay`](#recording-overlay)        | ポータル内に組み込みの停止コントロールをレンダリングします。          |
| [`RecordingOverlayProps`](#overlay-props)       | `RecordingOverlay` が受け取る props。         |
| [`RecorderBundle`](#recorder-bundle)            | 完了したイベントストリーム、ロケール一覧、オーバーレイ。           |
| [`RecorderConfig`](#recorder-config)            | `start()` に渡すソース優先のロケール一覧。             |
| [`RecorderStatus`](#recorder-status)            | レコーダーのライフサイクル状態。                        |
| [`FrameOption`](#frame-option)                  | キャプチャフレームの設定。                           |
| [スタイルとフォント](#styles-fonts)                      | キャプチャおよびリプレイ中のスタイルシートとフォントの挙動。          |
| [`DEFAULT_CONTENT_SELECTOR`](#content-selector) | デフォルトのフレーム付きコンテンツセレクター。                 |
| [`GT_EVENT`](#gt-event)                         | ストリームに埋め込まれるカスタム rrweb イベントタグ。          |

## `GTRecorder` [#gt-recorder]

アプリケーションのroot付近で `GTRecorder` を一度だけマウントします。待機中は何もレンダリングせず、録画中は `RecordingOverlay` を表示します。

```tsx
<GTRecorder
  harvest={{ loadTranslations, sourceLocale: 'en' }}
  onComplete={saveBundle}
/>
```

セッション開始時にレコーダーの設定がスナップショットとして保存されます。キャプチャ中にPropを変更しても、そのセッションのフレーム、ハーベストオプション、完了callbackには反映されません。

## `GTRecorderProps` [#gt-recorder-props]

| Prop              | 説明                                                    | 型                                  | 任意 | デフォルト                      |
| ----------------- | ----------------------------------------------------- | ---------------------------------- | -- | -------------------------- |
| `enabled`         | レコーダーの設定とレンダリングを有効にします。                               | `boolean`                          | はい | `true`                     |
| `contentSelector` | フレーム化するリージョンを選択します。                                   | `string`                           | はい | `DEFAULT_CONTENT_SELECTOR` |
| `frame`           | 選択したリージョンをキャプチャフレームに合わせて再配置します。                       | `FrameOption`                      | はい | `'none'`                   |
| `expose`          | 自動化用に、`start` と `stop` を持つ `window[name]` ハンドルを追加します。 | `string \| false`                  | はい | `false`                    |
| `onComplete`      | 停止が正常に完了するたびに、完成した バンドル を受け取ります。                      | `(bundle: RecorderBundle) => void` | はい | —                          |
| `harvest`         | ロケールオーバーレイの生成を設定します。                                  | `HarvestOptions`                   | はい | `{}`                       |
| `labels`          | 録画と停止のラベルをオーバーライドします。                                 | `{ rec?: string; stop?: string }`  | はい | 組み込みラベル                    |

ページをアンロードすると、アクティブなセッションは中断されます。中断されたセッションでは、翻訳のハーベストも `onComplete` の呼び出しも行われません。

## `useRecorder` [#use-recorder]

`useRecorder()` はモジュールレベルのレコーダーを監視し、[`UseRecorder`](#use-recorder-result) を返します。

同時に呼び出された `start()` は無視されます。アクティブな録画がない状態で `stop()` を呼び出すと `null` が返されます。起動準備中に呼び出すと、保留中のセッションがキャンセルされ、`null` が返されます。

## `UseRecorder` [#use-recorder-result]

| 値             | 説明                           | 型                                           |
| ------------- | ---------------------------- | ------------------------------------------- |
| `status`      | 現在のライフサイクル状態。                | `RecorderStatus`                            |
| `isRecording` | `status` が `recording` かどうか。 | `boolean`                                   |
| `start`       | フォントの埋め込み後にセッションを開始します。      | `(config: RecorderConfig) => Promise<void>` |
| `stop`        | キャプチャを停止し、翻訳をハーベストしてバンドルを返します。  | `() => Promise<RecorderBundle \| null>`     |

## `RecordingOverlay` [#recording-overlay]

`RecordingOverlay` は、`GTRecorder` で使用されるポータルベースのコントロールです。[`RecordingOverlayProps`](#overlay-props) を受け取ります。通常、アプリケーションから直接マウントすることはありません。

## `RecordingOverlayProps` [#overlay-props]

| Prop     | 説明                                             | 型                                 | 任意  | デフォルト   |
| -------- | ---------------------------------------------- | --------------------------------- | --- | ------- |
| `onStop` | 停止ボタンを処理します。                                   | `() => void`                      | いいえ | —       |
| `aspect` | キャプチャフレームのアスペクト比を設定します。`null` の場合は本来の寸法を保持します。 | `number \| null`                  | はい  | `null`  |
| `labels` | 録画と停止のラベルをオーバーライドします。                          | `{ rec?: string; stop?: string }` | はい  | 組み込みラベル |

## `RecorderBundle` [#recorder-bundle]

| フィールド     | 説明                                       | 型                                        | 任意  | デフォルト |
| --------- | ---------------------------------------- | ---------------------------------------- | --- | ----- |
| `events`  | 埋め込みロケールイベントおよびオーバーレイイベントを含む rrweb イベント。 | `eventWithTime[]`                        | いいえ | —     |
| `locales` | ソースロケールを先頭にした、追跡されたロケール。                 | `string[]`                               | いいえ | —     |
| `overlay` | ロケールから rrweb ノード ID への変換マップ。             | `Record<string, Record<number, string>>` | いいえ | —     |

このバンドルは JSON にシリアライズできます。ハーベスト が設定されていない場合でも、イベントストリームは無効にならず、`overlay` は空のままです。カタログローダーの失敗は該当するロケールにのみ影響します。より広範なハーベストの失敗が発生した場合は、全体のオーバーレイが空で返されます。ロケール一覧とオーバーレイはカスタムイベントとしても埋め込まれるため、イベントのみをエクスポートしても `gt-rrweb` のリプレイヤー向けのローカライズ済み再生メタデータは保持されます。

## `RecorderConfig` [#recorder-config]

`RecorderConfig` には、必須フィールド `locales: readonly string[]` が 1 つあります。キャプチャ中に表示するロケールを先頭に指定してください。以降のロケールは、キャプチャ停止後にハーベストされます。レコーダーがハーベストを実行するのは、リストに 2 つ以上のロケールが含まれている場合のみです。

## `RecorderStatus` [#recorder-status]

`RecorderStatus` は `'idle' | 'recording' | 'preparing'` です。`preparing` には、キャプチャ前のフォント準備とキャプチャ後のロケール収集の両方が含まれます。

## `FrameOption` [#frame-option]

`FrameOption` は `'none' | '16:9' | { aspect: number }` です。カスタムのアスペクトには、幅を高さで割った有限の正の値を指定してください。0、負の値、`NaN` を指定した場合は、frame なしと同じ挙動になります。

`'none'` はドキュメントのレイアウトを変更せず、記録されたビューポート全体を再生します。frame のない記録では、`contentSelector` によるトリミングは行われません。`'16:9'` またはカスタムのアスペクトを使用する場合は、記録前に対象の element へ `position: fixed` を適用してください。static に配置されたコンテンツを frame で囲むと、ビューポートの外へ移動してしまうことがあります。

## スタイルとフォント [#styles-fonts]

レコーダーは、CSS をシリアライズせずにスタイルシートへのリンクをそのまま保持します。そのため、リプレイが正しく表示されるかどうかは、元のスタイルシートのホストに引き続きアクセスできるかに左右される場合があります。

キャプチャの前に、レコーダーは読み取り可能な `@font-face` ルールで参照されているフォントファイルを埋め込みます。読み取れないスタイルシート、取得に失敗したフォントファイルや空のフォントファイル、および 5 MiB を超える個々のフォントファイルはスキップされます。スキップされたフォントは、リプレイ環境に応じてフォールバックします。

## `DEFAULT_CONTENT_SELECTOR` [#content-selector]

`DEFAULT_CONTENT_SELECTOR` は `main, [data-gt-content]` です。

## `GT_EVENT` [#gt-event]

| フィールド     | Tag          | 目的                              |
| --------- | ------------ | ------------------------------- |
| `nav`     | `gt-nav`     | SPA のナビゲーションを記録します。             |
| `locales` | `gt-locales` | トレース対象のロケール一覧とソースロケールを記録します。    |
| `i18n`    | `gt-i18n`    | 完全なスナップショット後に収集されたオーバーレイを保存します。 |

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.