xuguopeng/rrweb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update zh_CN Docs (#384)

Browse Source 
* update zh_CN guide, with latest API and options

* add receipes

* update receipes and guide

* update #329 add links to README
This commit is contained in:
yz-yu
2026-04-01 12:00:00 +08:00
committed by GitHub
parent 5678e3a062
commit 655f96da61
13 changed files with 621 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
guide.zh_CN.md
View File

@@ -1,5 +1,7 @@
# 使用指南
> 除通用的使用指南外，你可能还想通过[场景示例](./docs/receipes/index.zh_CN.md)了解特定场景下的使用方式，或是通过[设计文档](./docs)深入 rrweb 的技术细节。
## 安装
### 直接通过 `<script>` 引入
@@ -28,6 +30,33 @@ rrweb 代码分为录制和回放两部分，大多数时候用户在被录制
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/record/rrweb-record.min.js"></script>
```
#### 其它按需引入方式
除了仅包含录制代码的 `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 次事件重新制作一次全量快照<br />详见“重新制作快照”章节 |
| checkoutEveryNms | - | 每 N 毫秒重新制作一次全量快照<br />详见“重新制作快照”章节 |
| blockClass | 'rr-block' | 字符串或正则表达式，可用于自定义屏蔽元素的类名，详见“隐私”章节 |
| ignoreClass | 'rr-ignore' | 字符串或正则表达式，可用域自定义忽略元素的类名，详见“隐私”章节 |
| maskAllInputs | false | 将所有输入内容记录为 \* |
| maskInputOptions | {} | 选择将特定类型的输入框内容记录为 \*<br />类型详见[列表](https://github.com/rrweb-io/rrweb-snapshot/blob/6728d12b3cddd96951c86d948578f99ada5749ff/src/types.ts#L72) |
| inlineStylesheet | true | 是否将样式表内联 |
| hooks | {} | 各类事件的回调<br />类型详见[列表](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<playerConfig>);
使用 `rrweb-player` 时，也可以通过 `addEventListener` API 使用相同的事件功能，并且会获得 3 个额外的事件：
public on(event: string, handler: mitt.Handler): void;
public setConfig(config: Partial<playerConfig>): 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 工具