# General Translation Integrations: Replayer API
URL: https://generaltranslation.com/zh/docs/integrations/rrweb/reference/replayer.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用本地化文本叠加层和播放控件播放 rrweb bundle。gt-rrweb replayer 的 API 参考。

从 `gt-rrweb/replay` 导入 replayer 相关值。该入口文件导出 React 封装，即使你只使用 `createGTReplayer`，也需要 React、React DOM 18 或更高版本以及 `@rrweb/types`；DOM 播放器还需要安装可选的 `@rrweb/replay` peer 依赖。

## 概览 [#overview]

| API                                       | 描述                             |
| ----------------------------------------- | ------------------------------ |
| [`createGTReplayer`](#create-gt-replayer) | 将播放器挂载到 DOM 元素。                |
| [`GTReplayer`](#gt-replayer)              | `createGTReplayer` 的 React 封装。 |
| [`GTReplayerProps`](#replayer-props)      | `GTReplayer` 接受的属性。            |
| [`GTReplayerBundle`](#replayer-bundle)    | 事件流和可选的区域设置数据。                 |
| [`GTReplayerOptions`](#replayer-options)  | 初始区域设置、切换和调试选项。                |
| [`GTReplayerHandle`](#replayer-handle)    | 销毁已挂载的播放器。                     |

## `createGTReplayer` [#create-gt-replayer]

```ts
function createGTReplayer(
  container: HTMLElement,
  bundle: GTReplayerBundle,
  options?: GTReplayerOptions
): GTReplayerHandle;
```

该函数会挂载一个独立的播放器并开始播放。它包含带黑边的舞台、点击式光标、进度条、浅色和深色主题控制、全屏控制，以及 bundle 支持时的区域设置切换器。

容器的大小应由其父容器决定。移除或复用容器前，请调用 `destroy()`。

如果 bundle 中的事件少于两个，播放器内会显示错误，并返回一个句柄，其 `destroy()` 方法可安全调用且不执行任何操作。

## `GTReplayer` [#gt-replayer]

`GTReplayer` 会将 `createGTReplayer` 挂载到由 React 管理的容器中，并在卸载时销毁。`bundle`、`initialLocale`、`switchLocalesAllowed` 或 `debug` 发生变化时，会重新创建播放器。

## `GTReplayerProps` [#replayer-props]

| Prop                   | 描述                | Type               | 可选 | 默认                  |
| ---------------------- | ----------------- | ------------------ | -- | ------------------- |
| `bundle`               | 要播放的录制内容。         | `GTReplayerBundle` | 否  | —                   |
| `initialLocale`        | 挂载时渲染的区域设置。       | `string`           | 是  | `bundle.locales[0]` |
| `switchLocalesAllowed` | 显示区域设置控件，并允许实时切换。 | `boolean`          | 是  | `true`              |
| `debug`                | 接受拖放的录制 JSON 文件。  | `boolean`          | 是  | `false`             |
| `className`            | 应用于宿主容器的类名。       | `string`           | 是  | —                   |
| `style`                | 应用于宿主容器的内联样式。     | `CSSProperties`    | 是  | —                   |

## `GTReplayerBundle` [#replayer-bundle]

| 字段        | 描述                         | 类型                  | 可选 | 默认值 |
| --------- | -------------------------- | ------------------- | -- | --- |
| `events`  | rrweb 事件流。                 | `eventWithTime[]`   | 否  | —   |
| `locales` | 可用区域设置，源区域设置位于首位。          | `readonly string[]` | 是  | —   |
| `overlay` | 区域设置到 rrweb 节点 ID 文本映射的映射。 | `LocaleTextOverlay` | 是  | —   |

仅含原始事件的包会以录制时的源区域设置进行回放。`gt-rrweb` 发出的事件也可在事件流中携带区域设置和叠加层元数据。

## `GTReplayerOptions` [#replayer-options]

| 选项                     | 说明                                 | 类型        | 可选 | 默认      |
| ---------------------- | ---------------------------------- | --------- | -- | ------- |
| `initialLocale`        | 挂载时渲染的区域设置；如果该区域设置不在 bundle 中，则忽略。 | `string`  | 是  | 源区域设置   |
| `switchLocalesAllowed` | 启用播放器内的区域设置切换器。                    | `boolean` | 是  | `true`  |
| `debug`                | 启用通过拖放替换 bundle，以便进行本地检查。          | `boolean` | 是  | `false` |

切换区域设置会原地替换文本，无需重新构建播放内容。拖放无效文件时，播放器内会显示提示。

## `GTReplayerHandle` [#replayer-handle]

`GTReplayerHandle` 提供一个方法 `destroy(): void`，用于从容器中移除播放器及其事件监听器。

## Sitemap

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