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 工具