From 655f96da61520218b609f1824417eb8489cf6f87 Mon Sep 17 00:00:00 2001 From: yz-yu Date: Wed, 1 Apr 2026 12:00:00 +0800 Subject: [PATCH] Update zh_CN Docs (#384) * update zh_CN guide, with latest API and options * add receipes * update receipes and guide * update #329 add links to README --- README.zh_CN.md | 2 + docs/recipes/canvas.zh_CN.md | 24 ++++ docs/recipes/custom-event.zh_CN.md | 53 +++++++ docs/recipes/customize-replayer.zh_CN.md | 72 ++++++++++ docs/recipes/dive-into-event.zh_CN.md | 70 +++++++++ docs/recipes/export-to-video.zh_CN.md | 5 + docs/recipes/index.zh_CN.md | 65 +++++++++ docs/recipes/interaction.zh_CN.md | 19 +++ docs/recipes/live-mode.zh_CN.md | 27 ++++ docs/recipes/optimize-storage.zh_CN.md | 102 ++++++++++++++ docs/recipes/pagination.zh_CN.md | 23 +++ docs/recipes/record-and-replay.zh_CN.md | 30 ++++ guide.zh_CN.md | 172 +++++++++++++++++------ 13 files changed, 621 insertions(+), 43 deletions(-) create mode 100644 docs/recipes/canvas.zh_CN.md create mode 100644 docs/recipes/custom-event.zh_CN.md create mode 100644 docs/recipes/customize-replayer.zh_CN.md create mode 100644 docs/recipes/dive-into-event.zh_CN.md create mode 100644 docs/recipes/export-to-video.zh_CN.md create mode 100644 docs/recipes/index.zh_CN.md create mode 100644 docs/recipes/interaction.zh_CN.md create mode 100644 docs/recipes/live-mode.zh_CN.md create mode 100644 docs/recipes/optimize-storage.zh_CN.md create mode 100644 docs/recipes/pagination.zh_CN.md create mode 100644 docs/recipes/record-and-replay.zh_CN.md diff --git a/README.zh_CN.md b/README.zh_CN.md index 75f67676..8d2fa70c 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -22,6 +22,8 @@ rrweb 是 'record and replay the web' 的简写，旨在利用现代浏览器所 [**📚 rrweb 使用指南 📚**](./guide.zh_CN.md) +[**场景示例**](./docs/receipes/index.zh_CN.md) + ## 项目结构 rrweb 主要由 3 部分组成： diff --git a/docs/recipes/canvas.zh_CN.md b/docs/recipes/canvas.zh_CN.md new file mode 100644 index 00000000..c986e0a2 --- /dev/null +++ b/docs/recipes/canvas.zh_CN.md @@ -0,0 +1,24 @@ +# Canvas + +Canvas 是一种特殊的 HTML 元素，默认情况下其内容不会被 rrweb 观测。我们可以通过特定的配置让 rrweb 能够录制并回放 Canvas。 + +录制时包含 Canvas 内的内容： + +```js +rrweb.record({ + emit(event) {}, + // 对 canvas 进行录制 + recordCanvas: true, +}); +``` + +回放时对 Canvas 进行回放： + +```js +const replayer = new rrweb.Replayer(events, { + UNSAFE_replayCanvas: true, +}); +replayer.play(); +``` + +**回放 Canvas 将会关闭沙盒策略，导致一定风险**。 diff --git a/docs/recipes/custom-event.zh_CN.md b/docs/recipes/custom-event.zh_CN.md new file mode 100644 index 00000000..388d48ce --- /dev/null +++ b/docs/recipes/custom-event.zh_CN.md @@ -0,0 +1,53 @@ +# 自定义事件 + +录制时可能需要在特定的时间点记录一些特定含义的数据，如果希望这部分数据作为回放时的一部分，则可以通过自定义事件的方式实现。 + +开始录制后，我们就可以通过 `record.addCustomEvent` API 添加自定义事件： + +```js +// 开始录制 +rrweb.record({ + emit(event) { + ... + } +}) + +// 在开始录制后的任意时间点记录自定义事件，例如： +rrweb.record.addCustomEvent('submit-form', { + name: '姓名', + age: 18 +}) +rrweb.record.addCustomEvent('some-error', { + error +}) +``` + +`addCustomEvent` 接收两个参数，第一个是字符串类型的 `tag`，第二个是任意类型的 `payload`。 + +在回放时我们可以通过监听事件获取对应的事件，也可以通过配置 rrweb-player 在回放器 UI 的时间轴中展示对应事件。 + +**获取对应事件** + +```js +const replayer = new rrweb.Replayer(events); + +replayer.on('custom-event', (event) => { + console.log(event.tag, event.payload); +}); +``` + +**在 rrweb-player 中展示** + +```js +new rrwebPlayer({ + target: document.body, + props: { + events, + // 自定义各个 tag 在时间轴上的色值 + tags: { + 'submit-form': '#21e676', + 'some-error': 'red', + }, + }, +}); +``` diff --git a/docs/recipes/customize-replayer.zh_CN.md b/docs/recipes/customize-replayer.zh_CN.md new file mode 100644 index 00000000..e0db0d27 --- /dev/null +++ b/docs/recipes/customize-replayer.zh_CN.md @@ -0,0 +1,72 @@ +# 自定义回放 UI + +当 rrweb Replayer 和 rrweb-player 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。 + +你可以通过以下几种方式从不同角度自定义回放 UI： + +1. 使用 rrweb-player 时，通过覆盖 CSS 样式表定制 UI。 +2. 使用 rrweb-player 时，通过 `showController: false` 隐藏控制器 UI，重新实现控制器 UI。 +3. 通过 `insertStyleRules` 在回放页面（iframe）内定制 CSS 样式。 +4. 基于 rrweb Replayer 开发自己的回放器 UI。 + +## 实现控制器 UI + +使用 rrweb-player 时，可以隐藏其控制器 UI： + +```js +new rrwebPlayer({ + target: document.body, + props: { + events, + showController: false, + }, +}); +``` + +实现自己的控制器 UI 时，你可能需要与 rrweb-player 进行交互。 + +通过 API 控制 rrweb-player： + +```js +// 在播放和暂停间切换 +rrwebPlayer.toggle(); +// 播放 +rrwebPlayer.play(); +// 暂停 +rrwebPlayer.pause(); +// 更新 rrweb-player 宽高 +rrwebPlayer.$set({ + width: NEW_WIDTH, + height: NEW_HEIGHT, +}); +rrwebPlayer.triggerResize(); +// 切换否跳过无操作时间 +rrwebPlayer.toggleSkipInactive(); +// 设置播放速度为 2 倍 +rrwebPlayer.setSpeed(2); +// 跳转至播放 3 秒处 +rrwebPlayer.goto(3000); +``` + +通过监听事件获得 rrweb-player 的状态： + +```js +// 当前播放时间 +rrwebPlayer.addEventListener('ui-update-current-time', (event) => { + console.log(event.detail.payload); +}); + +// 当前播放状态 +rrwebPlayer.addEventListener('ui-update-player-state', (event) => { + console.log(event.detail.payload); +}); + +// 当前播放进度 +rrwebPlayer.addEventListener('ui-update-progress', (event) => { + console.log(event.detail.payload); +}); +``` + +## 基于 rrweb Replayer 开发自己的回放器 UI + +可以参照 [rrweb-player](https://github.com/rrweb-io/rrweb-player) 的方式进行开发。 diff --git a/docs/recipes/dive-into-event.zh_CN.md b/docs/recipes/dive-into-event.zh_CN.md new file mode 100644 index 00000000..b4124287 --- /dev/null +++ b/docs/recipes/dive-into-event.zh_CN.md @@ -0,0 +1,70 @@ +# 深入录制数据 + +录制数据是一组类型严格的 JSON 数据，通过熟悉其格式，可以更灵活的使用录制数据。 + +## 数据类型 + +每个 event 都拥有 `timestamp` 属性用于标记时间戳。 + +除此之外，也都拥有 `type` 属性标记 event 类型，其对应关系如下： + +``` +type -> EventType.DomContentLoaded +event -> domContentLoadedEvent + +type = EventType.Load +event -> loadedEvent + +type -> EventType.FullSnapshot +event -> fullSnapshotEvent + +type -> EventType.IncrementalSnapshot +event -> incrementalSnapshotEvent + +type -> EventType.Meta +event -> metaEvent + +type -> EventType.Custom +event -> customEvent +``` + +其中 EventType 是 Typescipt 的 numeric enum，在运行时是从 0 开始的数字，其类型定义详见[列表](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L10)。 + +其中 incrementalSnapshotEvent 代表增量数据，其具体增量类型可以通过 `event.data.source` 字段进行判断： + +``` +source -> IncrementalSource.Mutation +data -> mutationData + +source -> IncrementalSource.MouseMove +data -> mousemoveData + +source -> IncrementalSource.MouseInteraction +data -> mouseInteractionData + +source -> IncrementalSource.Scroll +data -> scrollData + +source -> IncrementalSource.ViewportResize +data -> viewportResizeData + +source -> IncrementalSource.Input +data -> inputData + +source -> IncrementalSource.TouchMove +data -> mouseInteractionData + +source -> IncrementalSource.MediaInteraction +data -> mediaInteractionData + +source -> IncrementalSource.StyleSheetRule +data -> styleSheetRuleData + +source -> IncrementalSource.CanvasMutation +data -> canvasMutationData + +source -> IncrementalSource.Font +data -> fontData +``` + +enum IncrementalSource 的定义详见[列表](https://github.com/rrweb-io/rrweb/blob/master/src/types.ts#L64)。 diff --git a/docs/recipes/export-to-video.zh_CN.md b/docs/recipes/export-to-video.zh_CN.md new file mode 100644 index 00000000..3474e287 --- /dev/null +++ b/docs/recipes/export-to-video.zh_CN.md @@ -0,0 +1,5 @@ +# 转换为视频 + +rrweb 录制的数据是一种高效、易于压缩的文本格式，可以用于像素级的回放。但如果有进一步将录制数据转换为视频的需求，同样可以通过一些工具实现。 + +**TBD** diff --git a/docs/recipes/index.zh_CN.md b/docs/recipes/index.zh_CN.md new file mode 100644 index 00000000..b14c8f1b --- /dev/null +++ b/docs/recipes/index.zh_CN.md @@ -0,0 +1,65 @@ +# 场景示例 + +> 除场景示例外，你可能还想通过[使用指南](../../guide.zh_CN.md)掌握 rrweb 常用 API，或是通过[设计文档](../)深入 rrweb 的技术细节。 + +## 场景列表 + +### 录制与回放 + +录制与回放时最常用的使用方式，适用于任何需要采集用户行为数据并重新查看的场景。 + +[链接](./record-and-replay.zh_CN.md) + +### 深入录制数据 + +录制数据是一组类型严格的 JSON 数据，通过熟悉其格式，可以更灵活的使用录制数据。 + +[链接](./dive-into-event.zh_CN.md) + +### 异步加载数据 + +当录制的数据较多时，一次性加载至回放页面可能带来较大的网络开销和较长的等待时间。这时可以采取数据分页的方式，异步地加载数据并回放。 + +[链接](./pagination.zh_CN.md) + +### 实时回放（直播） + +如果希望持续、实时地看到录制的数据，达到类似直播的效果，则可以使用实时回放 API。这个方式也适用于一些实时协同的场景。 + +[链接](./live-mode.zh_CN.md) + +### 自定义事件 + +录制时可能需要在特定的时间点记录一些特定含义的数据，如果希望这部分数据作为回放时的一部分，则可以通过自定义事件的方式实现。 + +[链接](./custom-event.zh_CN.md) + +### 回放时与 UI 交互 + +回放时的 UI 默认不可交互，但在特定场景下也可以通过 API 允许用户与回放场景进行交互。 + +[链接](./interaction.zh_CN.md) + +### 自定义回放 UI + +当 rrweb Replayer 和 rrweb-player 的 UI 不能满足需求时，可以通过自定义回放 UI 制作属于你自己的回放器。 + +[链接](./customize-replayer.zh_CN.md) + +### 转换为视频 + +rrweb 录制的数据是一种高效、易于压缩的文本格式，可以用于像素级的回放。但如果有进一步将录制数据转换为视频的需求，同样可以通过一些工具实现。 + +[链接](./export-to-video.zh_CN.md) + +### 优化存储容量 + +在一些场景下 rrweb 的录制数据量可能高于你的预期，这部分文档可以帮助你选择适用于你的存储优化策略。 + +[链接](./optimize-storage.zh_CN.md) + +### Canvas + +Canvas 是一种特殊的 HTML 元素，默认情况下其内容不会被 rrweb 观测。我们可以通过特定的配置让 rrweb 能够录制并回放 Canvas。 + +[链接](./canvas.zh_CN.md) diff --git a/docs/recipes/interaction.zh_CN.md b/docs/recipes/interaction.zh_CN.md new file mode 100644 index 00000000..9a054125 --- /dev/null +++ b/docs/recipes/interaction.zh_CN.md @@ -0,0 +1,19 @@ +# 回放时与 UI 交互 + +回放时的 UI 默认不可交互，但在特定场景下也可以通过 API 允许用户与回放场景进行交互。 + +```js +const replayer = new rrweb.Replayer(events); + +// 允许用户在回放的 UI 中进行交互 +replayer.enableInteract(); + +// 禁用用户在回放的 UI 中进行交互 +replayer.disableInteract(); +``` + +rrweb 使用 CSS 的 `pointer-events: none` 属性禁用交互。 + +这能够让回放更加稳定，例如避免用户点击回放中的超链接发生跳转等。 + +如果你希望允许用户交互，例如用户可以在回放时在输入框中进行输入，那么就可以调用 `enableInteract` API，但需要对不稳定的场景自行加以处理。 diff --git a/docs/recipes/live-mode.zh_CN.md b/docs/recipes/live-mode.zh_CN.md new file mode 100644 index 00000000..a2c6c206 --- /dev/null +++ b/docs/recipes/live-mode.zh_CN.md @@ -0,0 +1,27 @@ +# 实时回放（直播） + +如果希望持续、实时地看到录制的数据，达到类似直播的效果，则可以使用实时回放 API。这个方式也适用于一些实时协同的场景。 + +使用 rrweb Replayer 进行实时回放时，需要传入 `liveMode: true` 配置，并通过 `startLive` API 启动直播模式。 + +```js +const replayer = new rrweb.Replayer([], { + liveMode: true, +}); + +replayer.startLive(FIRST_EVENT.timestamp - BUFFER); +``` + +使用 `startLive` API 启动直播模式时，你可以传入一个可选参数，用于设置基线时间戳，这对于需要一定缓冲时间的直播场景非常有用。 + +例如录制时的第一个事件记录于 1500 这个时间点，实时回放时传入 `startLive(1500)` 就会让回放器将基线时间戳定为 1500，并用于计算后续事件的延迟时间。 + +但这有时会让实时回放看起来卡顿，因为数据的传输需要一定的时间（例如网络延迟），同时一些事件因为节流的性能优化会延迟发出（例如鼠标移动）。 + +因此我们可以通过 `startLive` 传入一个较小值的方式来提供一个缓冲时间，例如 `startLive(500)` 就会让回放总是延迟 1 秒播放。如果传输延迟小于 1 秒，则观看者不会感到卡顿。 + +启动直播模式后，可以通过 `addEvent` API 不断将最新的事件传入回放器中： + +```js +replayer.addEvent(NEW_EVENT); +``` diff --git a/docs/recipes/optimize-storage.zh_CN.md b/docs/recipes/optimize-storage.zh_CN.md new file mode 100644 index 00000000..d982cfd1 --- /dev/null +++ b/docs/recipes/optimize-storage.zh_CN.md @@ -0,0 +1,102 @@ +# 优化存储容量 + +在一些场景下 rrweb 的录制数据量可能高于你的预期，这部分文档可以帮助你选择适用于你的存储优化策略。 + +优化策略分为以下几类： + +- 通过屏蔽 DOM 元素，减少录制的内容 +- 通过 sampling 配置抽样策略，减少录制的数据 +- 通过去冗、压缩，减少数据存储体积 + +## 屏蔽 DOM 元素 + +一些特定 DOM 元素可能会产生大量的录制数据，而这些数据未必是回放时关注的，这种情况下可以选择将这些 DOM 元素进行屏蔽，不录制其内容。 + +常见的大数据量 DOM 元素包括： + +- 长列表 +- 复杂的 SVG +- 包含 JS 控制动画的元素 + +## 抽样策略 + +录制时通过 sampling 配置可以让特定数据以抽样的形式减少录制频率： + +**示例 1** + +```js +rrweb.record({ + emit(event) {}, + sampling: { + // 不录制鼠标移动事件 + mousemove: false + // 不录制鼠标交互事件 + mouseInteraction: false, + // 设置滚动事件的触发频率 + scroll: 150 // 每 150ms 最多触发一次 + // 设置输入事件的录制时机 + input: 'last' // 连续输入时，只录制最终值 + } +}) +``` + +**示例 2** + +```js +rrweb.record({ + emit(event) {}, + sampling: { + // 定义不录制的鼠标交互事件类型，可以细粒度的开启或关闭对应交互录制 + mouseInteraction: { + MouseUp: false, + MouseDown: false, + Click: false, + ContextMenu: false, + DblClick: false, + Focus: false, + Blur: false, + TouchStart: false, + TouchEnd: false, + }, + }, +}); +``` + +## 压缩 + +### 基于 packFn 的单数据压缩 + +rrweb 内包含了基于 pako 的简单压缩 rrweb.pack，在录制时可以作为 `packFn` 传入。 + +```js +rrweb.record({ + emit(event) {}, + packFn: rrweb.pack, +}); +``` + +回放时通用需要传入 rrweb.unpack 作为 `unpackFn` 传入。 + +```js +const replayer = new rrweb.Replayer(events, { + unpackFn: rrweb.unpack, +}); +``` + +### 批量压缩 + +基于 packFn 的单数据压缩以每个 event 数据为单位进行压缩，但这很多时候不能发挥 rrweb 录制数据易于压缩的优势。 + +因此**更加推荐**在服务端实现多个 event 的批量压缩，例如将单次用户操作产生的所有 event 数据进行一次压缩，对于 gzip 等压缩算法来说更为友好。 + +## 去冗 + +另一个优化存储容量的思路是去冗。 + +为了模拟 hover 等需求，rrweb 会尽可能的将 CSS 样式 inline 在录制数据中。 + +可以想象，如果使用 rrweb 录制每个用户对 github.com 的访问，则会在录制数据中保存大量重复的样式表内容。 + +可以通过遍历录制数据，将包含样式表的内容提取单独保存的方式，将这部分相同数据仅保存一份。 + +另一方面，全量快照类的数据也存在同样的问题，可以使用同样的思路去冗，减少存储总量。 diff --git a/docs/recipes/pagination.zh_CN.md b/docs/recipes/pagination.zh_CN.md new file mode 100644 index 00000000..92d5ed1e --- /dev/null +++ b/docs/recipes/pagination.zh_CN.md @@ -0,0 +1,23 @@ +# 异步加载数据 + +当录制的数据较多时，一次性加载至回放页面可能带来较大的网络开销和较长的等待时间。这时可以采取数据分页的方式，异步地加载数据并回放。 + +rrweb 中用于实现异步加载数据的 API 非常简单直观： + +```js +const replayer = new rrweb.Replayer(events); + +replayer.addEvent(NEW_EVENT); +``` + +只需要调用 `addEvent` 传入新的数据，rrweb 就会自动处理其中的时间关系，以最恰当的方式进行回放。 + +如果需要异步加载多个数据，只需这样使用： + +```js +const replayer = new rrweb.Replayer(events); + +for (const event of NEW_EVENTS) { + replayer.addEvent(event); +} +``` diff --git a/docs/recipes/record-and-replay.zh_CN.md b/docs/recipes/record-and-replay.zh_CN.md new file mode 100644 index 00000000..39a40d59 --- /dev/null +++ b/docs/recipes/record-and-replay.zh_CN.md @@ -0,0 +1,30 @@ +# 录制与回放 + +录制与回放时最常用的使用方式，适用于任何需要采集用户行为数据并重新查看的场景。 + +仅需一个函数调用就可以录制当前页面： + +```js +const stopFn = rrweb.record({ + emit(event) { + // 保存获取到的 event 数据 + } +}) +``` + +你可以使用任何方式保存录制的数据，例如通过网络请求将数据传入至后端持久化保存，但请确保： + +- 一组录制的数据按照 event.timestamp 中的时间戳从小至大保存 +- 完整保存数据，不缺失任何一个 event。 + +如果需要手动停止录制，可以调用返回的 `stopFn` 函数。 + +回放时只需要获取一段录制数据，并传入 rrweb 提供的 Replayer： + +```js +const events = GET_YOUR_EVENTS + +const replayer = new rrweb.Replayer(events); +replayer.play(); +``` + diff --git a/guide.zh_CN.md b/guide.zh_CN.md index 58fb20c5..e0ce2f33 100644 --- a/guide.zh_CN.md +++ b/guide.zh_CN.md @@ -1,5 +1,7 @@ # 使用指南 +> 除通用的使用指南外，你可能还想通过[场景示例](./docs/receipes/index.zh_CN.md)了解特定场景下的使用方式，或是通过[设计文档](./docs)深入 rrweb 的技术细节。 + ## 安装 ### 直接通过 ` ``` +#### 其它按需引入方式 + +除了仅包含录制代码的 `record/rrweb-record-min.js` 之外，rrweb 还提供了其它多种可选的打包文件。所有包含 `.min` 的文件为同名文件的压缩版。 + +```shell +# 包含录制、回放、压缩数据、解压缩数据 +rrweb-all.js +rrweb-all.min.js +# 包含录制、回放 +rrweb.js +rrweb.min.js +# 回放所需的样式文件 +rrweb.min.css +# 录制 +record/rrweb-record.js +record/rrweb-record.min.js +# 压缩数据 +record/rrweb-record-pack.js +record/rrweb-record-pack.min.js +# 回放 +replay/rrweb-replay.js +replay/rrweb-replay.min.js +# 解压缩数据 +replay/rrweb-replay-unpack.js +replay/rrweb-replay-unpack.min.js +``` + ### 通过 npm 引入 ```shell @@ -98,6 +127,26 @@ function save() { setInterval(save, 10 * 1000); ``` +#### 配置参数 + +`rrweb.record(config)` 的 config 部分接受以下参数 + +| key | 默认值 | 功能 | +| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| emit | 必填 | 获取当前录制的数据 | +| checkoutEveryNth | - | 每 N 次事件重新制作一次全量快照
详见“重新制作快照”章节 | +| checkoutEveryNms | - | 每 N 毫秒重新制作一次全量快照
详见“重新制作快照”章节 | +| blockClass | 'rr-block' | 字符串或正则表达式，可用于自定义屏蔽元素的类名，详见“隐私”章节 | +| ignoreClass | 'rr-ignore' | 字符串或正则表达式，可用域自定义忽略元素的类名，详见“隐私”章节 | +| maskAllInputs | false | 将所有输入内容记录为 \* | +| maskInputOptions | {} | 选择将特定类型的输入框内容记录为 \*
类型详见[列表](https://github.com/rrweb-io/rrweb-snapshot/blob/6728d12b3cddd96951c86d948578f99ada5749ff/src/types.ts#L72) | +| inlineStylesheet | true | 是否将样式表内联 | +| hooks | {} | 各类事件的回调
类型详见[列表](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L207) | +| packFn | - | 数据压缩函数，详见[优化存储策略](./docs/receipes/optimize-storage.zh_CN.md) | +| sampling | - | 数据抽样策略，详见[优化存储策略](./docs/receipes/optimize-storage.zh_CN.md) | +| recordCanvas | false | 是否记录 canvas 内容 | +| collectFonts | false | 是否记录页面中的字体文件 | + #### 隐私 页面中可能存在一些隐私相关的内容不希望被录制，rrweb 为此做了以下支持： @@ -105,6 +154,7 @@ setInterval(save, 10 * 1000); - 在 HTML 元素中添加类名 `.rr-block` 将会避免该元素及其子元素被录制，回放时取而代之的是一个同等宽高的占位元素。 - 在 HTML 元素中添加类名 `.rr-ignore` 将会避免录制该元素的输入事件。 - `input[type="password"]` 类型的密码输入框默认不会录制输入事件。 +- 配置中还有更为丰富的隐私保护选项。 #### 重新制作快照 @@ -200,22 +250,47 @@ const replayer = new rrweb.Replayer(events); replayer.play(); ``` +#### 使用 API 控制回放 + +```js +const replayer = new rrweb.Replayer(events); + +//播放 +replayer.play(); + +// 从第 3 秒的内容开始播放 +replayer.play(3000); + +// 暂停 +replayer.pause(); + +// 暂停至第 5 秒处 +replayer.pause(5000); +``` + #### 配置参数 可以通过 `new rrweb.Replayer(events, options)` 的方式向 rrweb 传递回放时的配置参数，具体配置如下： -| key | 默认值 | 功能 | -| ------------ | ------------- | ------------------------------- | -| speed | 1 | 回放倍速 | -| root | document.body | 回放时使用的 HTML 元素 | -| loadTimeout | 0 | 加载异步样式表的超时时长 | -| skipInactive | false | 是否快速跳过无用户操作的阶段 | -| showWarning | true | 是否在回放过程中打印警告信息 | -| showDebug | false | 是否在回放过程中打印 debug 信息 | +| key | 默认值 | 功能 | +| ------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| speed | 1 | 回放倍速 | +| root | document.body | 回放时使用的 HTML 元素 | +| loadTimeout | 0 | 加载异步样式表的超时时长 | +| skipInactive | false | 是否快速跳过无用户操作的阶段 | +| showWarning | true | 是否在回放过程中打印警告信息 | +| showDebug | false | 是否在回放过程中打印 debug 信息 | +| blockClass | 'rr-block' | 需要在回放时展示为隐藏区域的元素类名 | +| liveMode | false | 是否开启直播模式 | +| inertStyleRules | [] | 可以传入多个 CSS rule string，用于自定义回放时 iframe 内的样式 | +| triggerFocus | true | 回放时是否回放 focus 交互 | +| UNSAFE_replayCanvas | false | 回放时是否回放 canvas 内容，**开启后将会关闭沙盒策略，导致一定风险** | +| mouseTail | true | 是否在回放时增加鼠标轨迹。传入 false 可关闭，传入对象可以定制轨迹持续时间、样式等，配置详见[类型](https://github.com/rrweb-io/rrweb/blob/9488deb6d54a5f04350c063d942da5e96ab74075/src/types.ts#L407) | +| unpackFn | - | 数据解压缩函数，详见[优化存储策略](./docs/receipes/optimize-storage.zh_CN.md) | #### 使用 rrweb-player -rrweb 自带的回放只提供所有的 JS API 以及最基本的 UI，如果需要更强的回放播放器 UI，可以使用 rrweb-player。 +rrweb 自带的回放只提供所有的 JS API 以及最基本的 UI，如果需要功能更强的回放播放器 UI，可以使用 rrweb-player。 ##### 安装 @@ -237,57 +312,68 @@ npm install --save rrweb-player ##### 使用 +通过 props 传入 events 数据及配置项 + ```js new rrwebPlayer({ target: document.body, // 可以自定义 DOM 元素 - data: { + // 配置项 + props: { events, }, }); ``` -## API +##### 配置项参数 -### rrweb +| key | 默认值 | 功能 | +| -------------- | ------------ | ----------------------------------------------------- | +| events | [] | 包含回放所需的数据 | +| width | 1024 | 播放器宽度 | +| height | 576 | 播放器高度 | +| autoPlay | true | 是否自动播放 | +| speedOption | [1, 2, 4, 8] | 倍速播放可选值 | +| showController | true | 是否显示播放器控制 UI | +| tags | {} | 可以以 key value 的形式展示自定义事件在时间轴上的颜色 | +| ... | - | 其它所有 rrweb Replayer 的配置参数均可透传 | -#### rrweb.record +#### 事件 -```typescript -type record = (options: recordOptions) => listenerHandler; +开发者可能希望监听回放时的各类事件，例如在跳过无用户操作的时间时给用户一些提示。 -type recordOptions = { - emit: (e: eventWithTime) => void; -}; -type listenerHandler = () => void; +rrweb 的 Replayer 提供了 `on` API 用于提供该功能 + +```js +const replayer = new rrweb.Replayer(events); +replayer.on(EVENT_NAME, (payload) => { + ... +}) ``` -#### rrweb.Replayer +其包含的事件如下： -```typescript -class Replayer { - public wrapper: HTMLDivElement; +| 事件类型 | 描述 | 值 | +| ---------------------- | ---------------------- | ----------------- | +| start | 回放开始 | - | +| pause | 回放暂停 | - | +| finish | 回放完成 | - | +| resize | 回放视图大小发生变化 | { width, height } | +| fullsnapshot-rebuilded | 全量快照完成重建 | event | +| load-stylesheet-start | 开始加载远端样式表 | - | +| load-stylesheet-end | 加载远端样式表完成 | - | +| skip-start | 开始跳过无用户操作时间 | { speed } | +| skip-end | 结束无用户操作时间 | { speed } | +| mouse-interaction | 回放鼠标交互事件 | { type, target } | +| event-cast | 回放 event | event | +| custom-event | 回放自定义事件 | event | - constructor(events: eventWithTime[], config?: Partial); +使用 `rrweb-player` 时，也可以通过 `addEventListener` API 使用相同的事件功能，并且会获得 3 个额外的事件： - public on(event: string, handler: mitt.Handler): void; - public setConfig(config: Partial): void; - public getMetaData(): playerMetaData; - public getTimeOffset(): number; - public play(timeOffset?: number): void; - public pause(timeOffset?: number): void; -} - -type playerConfig = { - speed: number; - root: Element; - loadTimeout: number; - skipInactive: Boolean; -}; - -type playerMetaData = { - totalTime: number; -}; -``` +| 事件类型 | 描述 | 值 | +| ---------------------- | -------------- | ----------------------- | +| ui-update-current-time | 当前回放时间点 | { detail: { payload } } | +| ui-update-player-state | 当前回放状态 | { detail: { payload } } | +| ui-update-progress | 当前回放百分比 | { detail: { payload } } | ## REPL 工具