# General Translation Integrations: Recorder API
URL: https://generaltranslation.com/zh/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` 接受的属性。         |
| [`useRecorder`](#use-recorder)                  | 启动和停止模块级录制器。                |
| [`UseRecorder`](#use-recorder-result)           | `useRecorder` 返回的录制控件和当前状态。 |
| [`RecordingOverlay`](#recording-overlay)        | 在 portal 中渲染内置停止控件。         |
| [`RecordingOverlayProps`](#overlay-props)       | `RecordingOverlay` 接受的属性。   |
| [`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]

在靠近应用根部的位置挂载一次 `GTRecorder`。空闲时不渲染任何内容，录制时显示 `RecordingOverlay`。

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

录制器会在会话开始时对配置生成快照。捕获期间对 Prop 所做的更改不会影响该会话的捕获框、采集选项或完成回调。

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

| Prop              | 描述                                                 | Type                               | Optional | Default                    |
| ----------------- | -------------------------------------------------- | ---------------------------------- | -------- | -------------------------- |
| `enabled`         | 启用录制器的配置和渲染。                                       | `boolean`                          | 是        | `true`                     |
| `contentSelector` | 选择要框定的区域。                                          | `string`                           | 是        | `DEFAULT_CONTENT_SELECTOR` |
| `frame`           | 将所选区域重新布局到捕获框中。                                    | `FrameOption`                      | 是        | `'none'`                   |
| `expose`          | 添加包含 `start` 和 `stop` 方法的 `window[name]` 句柄，用于自动化。 | `string \| false`                  | 是        | `false`                    |
| `onComplete`      | 每次成功停止后接收生成的 bundle。                               | `(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`        | 停止捕获、采集翻译，并返回 bundle。     | `() => Promise<RecorderBundle \| null>`     |

## `RecordingOverlay` [#recording-overlay]

`RecordingOverlay` 是供 `GTRecorder` 使用的基于 Portal 的控件。它接受 [`RecordingOverlayProps`](#overlay-props)。大多数应用不会直接挂载它。

## `RecordingOverlayProps` [#overlay-props]

| Prop     | 描述                         | Type                              | Optional | Default |
| -------- | -------------------------- | --------------------------------- | -------- | ------- |
| `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>>` | 否  | —   |

该 bundle 可序列化为 JSON。采集未配置时，`overlay` 会保持为空，但不会导致事件流失效。catalog 加载器失败只影响该区域设置；而更大范围的采集失败会返回整体为空的叠加层。区域设置列表和叠加层同样以自定义事件的形式嵌入其中，因此仅导出事件也能为 `gt-rrweb` 回放器保留本地化的播放元数据。

## `RecorderConfig` [#recorder-config]

`RecorderConfig` 包含一个必填字段：`locales: readonly string[]`。请将捕获期间显示的区域设置置于首位；捕获结束后会采集后续区域设置。仅当该列表包含至少两个区域设置时，录制器才会执行采集。

## `RecorderStatus` [#recorder-status]

`RecorderStatus` 的取值为 `'idle' | 'recording' | 'preparing'`。`preparing` 包括捕获前的字体准备以及捕获后的区域设置收集。

## `FrameOption` [#frame-option]

`FrameOption` 为 `'none' | '16:9' | { aspect: number }`。自定义宽高比必须是有限的正数，以宽度除以高度表示。零、负值和 `NaN` 的效果等同于不使用捕获框。

`'none'` 会保持文档布局不变，并重放完整的录制视口；对于未加捕获框的录制，`contentSelector` 不会进行裁剪。若使用 `'16:9'` 或自定义宽高比，请在录制前为选中的元素设置 `position: fixed`；对静态定位的内容加捕获框可能会将其移出视口。

## 样式与字体 [#styles-fonts]

录制器只保留样式表链接，不会将其 CSS 序列化保存。因此，回放可能依赖原始样式表所在主机始终可访问。

在捕获之前，录制器会嵌入可读的 `@font-face` 规则所引用的字体文件，并跳过无法读取的样式表、加载失败或内容为空的字体文件，以及单个体积超过 5 MiB 的字体文件。被跳过的字体将根据回放环境进行回退。

## `DEFAULT_CONTENT_SELECTOR` [#content-selector]

`DEFAULT_CONTENT_SELECTOR` 默认为 `main, [data-gt-content]`。

## `GT_EVENT` [#gt-event]

| 字段        | 标签           | 用途                  |
| --------- | ------------ | ------------------- |
| `nav`     | `gt-nav`     | 记录 SPA 导航。          |
| `locales` | `gt-locales` | 记录追踪到的区域设置列表和源区域设置。 |
| `i18n`    | `gt-i18n`    | 在完整翻译快照后存储收集到的叠加层。  |

## Sitemap

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