rrweb-lite
v1.0.5
Published
轻量级录屏回放库,兼容 IE9+,不含业务逻辑
Maintainers
Readme
rrweb-lite
轻量级录屏回放库,提供两个核心工具类:
Recorder:负责录制页面行为,产出可持久化的eventsPlayer:负责读取events并在页面中回放
适合做操作留痕、问题复现、流程回放这类场景。库本身不包含业务逻辑,数据上传、如何展示 UI 播放,都由业务侧决定。 使用可参考 example
安装
npm install rrweb-lite工具类说明
Recorder
用于录制当前页面的用户行为,会采集页面快照、用户交互事件。
Player
用于回放 Recorder 产出的事件数据,自动创建播放容器、支持播放、暂停、停止、调速和进度显示。
如何使用
最常见的流程只有 3 步:
- 用
Recorder录制页面操作 - 通过
getEvents()拿到事件数据并保存 - 用
Player做回放
1. 录制
import rrwebLite from 'rrweb-lite'
const { Recorder } = rrwebLite
const recorder = new Recorder({
snapshotInterval: 5000, // 快照间隔
idleTimeout: 5000, // 空闲超时
debug: false, // 是否输出调试日志
/**
* 快照事件回调,参数为快照事件数组
* @param {Array} events
*/
onSnapshot: function (events) {
// 这里可以选择上传或暂存
sessionStorage.setItem('rr-events', JSON.stringify(events))
}
})
recorder.start()
// 结束录制时取出数据
const events = recorder.getEvents()
recorder.stop()2. 回放
import rrwebLite from 'rrweb-lite'
const { Player } = rrwebLite
const player = new Player({
container: document.getElementById('player-box'), // 播放容器
speed: 1, // 初始倍速
/**
* 播放状态回调,参数为播放状态对象
* @param {Object} state
*/
onStateChange: function (state) {
console.log(state.cursor + ' / ' + state.sortedEvents.length)
}
})
player.setEvents(events)
player.play()3. 常见控制
player.pause()
player.stop()
player.setSpeed(2)
const state = player.getState()
player.destroy()常用参数
Recorder 参数
new Recorder({
snapshotInterval: 5000, // 快照间隔,默认 5000ms
idleTimeout: 5000, // 空闲超时,默认等于 snapshotInterval
minSnapshotGap: 250, // 两帧最小间隔,过近则合并,默认 250ms
debug: false, // 是否输出调试日志
onSnapshot: function (events) {},
onEvent: function (event) {},
// ===== 开录暖拍(1.0.4+)=====
// 解决:首帧拍在 SPA 异步渲染之前(如列表接口未返回的空态页),
// 而下一帧周期快照已跳到用户操作后的新页面,导致回放看不到首屏真实内容。
// 策略:开录后 warmUpMs 内,DOM 变化体量达 warmUpMinDelta 且稳定 warmUpSettle 毫秒后补拍,
// 最多补 warmUpMaxShots 帧,到时/拍满自动关闭。
warmUp: true, // 是否启用,默认 true
warmUpMs: 15000, // 暖拍时间窗,默认 15000ms
warmUpMaxShots: 3, // 最多补拍帧数,默认 3
warmUpSettle: 500, // DOM 稳定多久后拍,默认 500ms
warmUpMinDelta: 150 // 变化体量阈值(按节点序列化长度估算),过滤轮播/倒计时等小改动,默认 150
})Player 参数
new Player({
container: '#player-box', // DOM 节点或选择器
speed: 1, // 初始倍速
maxDelay: 1500, // 单步最大播放等待时间
onStateChange: function (state) {}
})常用方法
Recorder 方法
start():开始录制stop():停止录制getEvents():获取当前录制结果clear():清空当前缓存事件getStats():获取录制状态,如事件数、是否空闲、最后一条事件等
Player 方法
setEvents(events):设置回放数据play():开始播放pause():暂停播放stop():停止并重置setSpeed(speed):设置播放倍速getState():获取当前播放状态destroy():销毁播放器实例
事件数据格式
{ type: 'snapshot', html: '<!doctype...>', timestamp: 1720000000000 }
{ type: 'click', x: 100, y: 200, path: '//*[@id="btn"]', timestamp: 1720000001000 }
{ type: 'input', value: 'hello', path: '//HTML[1]/BODY[1]/INPUT[1]', timestamp: 1720000002000 }
// 1.0.5+:勾选框/单选 change 会带 inputKind:'checked' 与 checked 布尔值,回放可正确勾显
{ type: 'input', inputKind: 'checked', checked: true, path: '...', value: 'on', timestamp: 1720000003000 }屏蔽录制
不希望被录制的节点,可以加 rr-block:
<div class="rr-block">敏感内容,不录制</div>示例
- 本地演示页面:
example/index.html - 包入口导出:
index.js
兼容性
Recorder:IE9+Player:IE9+
