rrweb 异步分页加载与回放实战深入解析 Replayer.addEvent 的事件追加机制【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb当录制的会话数据体积较大时一次性将全部事件加载到回放页面会带来显著的网络开销与白屏等待时间。rrweb 提供了极简的Replayer.addEventAPI允许开发者按需分页加载数据并增量追加到正在运行的回放实例中由回放引擎自动处理事件间的时间关系。读完本文你将掌握基于addEvent实现异步分页回放的标准姿势并理解其背后状态机按时间戳插入、延迟调度与 live 模式协同的完整原理。为什么需要异步加载事件rrweb 的录制产物是一串带时间戳的事件数组eventWithTime[]每条事件都记录了 DOM 变更、交互行为、滚动位置等快照增量。当录制时间很长时事件总量可能达到数万甚至数十万条首屏加载开销大将完整数据一次性拉取到浏览器传输耗时和解析耗时都会明显拖慢回放页面的初始化等待时间长用户在数据完全到达之前无法看到任何内容体验与加载中无异资源浪费用户可能只查看片段全量数据并不总是必要。更合理的方案是分页pagination先加载第一条快照Meta 事件 FullSnapshot与一小段增量事件让回放先跑起来再随着播放进度逐步异步拉取后续页面的事件并追加给回放器。rrweb 官方文档 异步加载数据 给出的正是这一思路的最小实现。核心 APIReplayer.addEventrrweb 中用于实现异步加载数据的 API 非常简单直观来自回放器类Replayer的公开方法addEvent只需调用它传入新的数据rrweb 就会自动处理其中的时间关系以最恰当的方式进行回放。追加单个事件import { Replayer } from rrweb/replay; const replayer new Replayer(events); replayer.addEvent(NEW_EVENT);NEW_EVENT是任意一条后续加载到的eventWithTime事件。在真实分页场景中它通常来自你向后端发起的下一页数据请求的响应。循环追加多个事件如果需要异步加载多个数据只需循环调用即可import { Replayer } from rrweb/replay; const replayer new Replayer(events); for (const event of NEW_EVENTS) { replayer.addEvent(event); }代码层面只多了三行但这条循环背后的行为值得注意批量追加时并不要求传入的事件严格按时间递增。由于addEvent内部会按时间戳做有序插入下文详述乱序到达的事件也会被正确地排进回放序列。引入路径说明原文档示例使用rrweb/replay包名它对应仓库中的 packages/replay该包将Replayer从rrweb重新导出并附带回放所需的样式import { Replayer } from rrweb/replay; import rrweb/replay/dist/style.css;在 monorepo 内部Replayer的直接实现位于 packages/rrweb/src/replay/index.ts因此你同样可以直接从rrweb导入。addEvent 的底层实现从入口到状态机addEvent之所以自动处理时间关系是因为它背后串起了三个核心模块Replayer实例方法、基于 XState 的播放状态机machine.ts以及事件调度器Timertimer.ts。入口方法类型归一化与异步投递packages/rrweb/src/replay/index.ts#L572-L582 中addEvent的实现如下public addEvent(rawEvent: eventWithTime | string) { const event this.config.unpackFn ? this.config.unpackFn(rawEvent as string) : (rawEvent as eventWithTime); if (indicatesTouchDevice(event)) { this.mouse.classList.add(touch-device); } void Promise.resolve().then(() this.service.send({ type: ADD_EVENT, payload: { event } }), ); }从源码可以提炼出三个设计要点支持字符串入参rawEvent既可以是对象也可以是字符串。当配置了unpackFn例如配合 rrweb packer 插件的解包函数时字符串会先被解包成结构化事件再进行后续处理触屏设备标记如果追加的事件表明当前是触屏设备indicatesTouchDevice回放器会自动为鼠标光标元素添加touch-device类保证光标渲染形态正确微任务异步投递addEvent通过Promise.resolve().then(...)把ADD_EVENT动作投递给状态机而不是同步执行。这意味着你在一次事件循环里连续调用多次addEvent会被统一收拢到下一轮微任务中依序处理天然避免了批处理时的重入问题。状态机三个状态统一响应 ADD_EVENT播放状态机packages/rrweb/src/replay/machine.ts定义了playing、paused、live三种状态而ADD_EVENT在三种状态下都能被响应playing态追加事件并继续播放target: playing, actions: [addEvent]paused态追加事件但保持暂停target: paused, actions: [addEvent]live态追加事件并维持直播模式target: live, actions: [addEvent]。也就是说无论回放器当前处于播放、暂停还是直播状态addEvent都能安全生效这正是它适合边播边拉数据场景的根本原因。测试 packages/rrweb/test/replayer.test.ts#L905-L935 也验证了在liveMode: true下调用startLive()后继续addEvent回放器不会误触发Finish事件。addEvent action按时间戳二分插入状态机中真正干活的addEventaction 位于 packages/rrweb/src/replay/machine.ts#L238-L279核心逻辑如下addEvent: assign((ctx, machineEvent) { const { baselineTime, timer, events } ctx; if (machineEvent.type ADD_EVENT) { const { event } machineEvent.payload; addDelay(event, baselineTime); let end events.length - 1; if (!events[end] || events[end].timestamp event.timestamp) { // fast track events.push(event); } else { // 二分查找插入位置保证 events 始终按 timestamp 升序 let insertionIndex -1; let start 0; while (start end) { const mid Math.floor((start end) / 2); if (events[mid].timestamp event.timestamp) { start mid 1; } else { end mid - 1; } } if (insertionIndex -1) { insertionIndex start; } events.splice(insertionIndex, 0, event); } const isSync event.timestamp baselineTime; const castFn getCastFn(event, isSync); if (isSync) { castFn(); // 落后于当前进度的事件立即同步回放 } else if (timer.isActive()) { timer.addAction({ // 未来事件挂入定时器按 delay 调度 doAction: () { castFn(); }, delay: event.delay!, }); } } return { ...ctx, events }; }),关键行为有三条有序插入若新事件的时间戳不早于当前最后一个事件fast track 快路径直接push否则通过二分查找找到插入位置执行splice保证事件数组始终按timestamp升序。这就是乱序到达的事件也能被正确回放的原理追加即算延迟addDelay会在追加时立刻根据事件时间戳与当前baselineTime基线时间计算出event.delay同步/异步分流时间戳早于基线时间的事件即应该已经播过的部分直接同步执行castFn立即生效时间戳在未来的事件则通过timer.addAction挂入调度队列等待Timer触发。另外若Timer尚未激活例如播放前批量 addEvent事件只会进入数组排队不会提前触发。Timer 与 addDelay时间关系如何被自动处理Timer类packages/rrweb/src/replay/timer.ts维护一个按delay排序的动作队列并在每一帧rafCheck中取出timeOffset action.delay的动作执行从而把事件时间戳翻译成播放时钟上的触发时刻。addDelay函数timer.ts#L119-L137对鼠标移动事件做了专门处理由于 mousemove 在录制端经过节流合并event.timestamp并不是真实移动时刻因此需要遍历data.positions[0].timeOffset还原首个采样点的真实时间戳后再计算延迟if ( event.type EventType.IncrementalSnapshot event.data.source IncrementalSource.MouseMove event.data.positions event.data.positions.length ) { const firstOffset event.data.positions[0].timeOffset; const firstTimestamp event.timestamp firstOffset; // timeOffset 为负偏移 event.delay firstTimestamp - baselineTime; return firstTimestamp - baselineTime; } event.delay event.timestamp - baselineTime;此外Timer.addAction同样使用fast track 二分插入timer.ts#L28-L44且在实时场景live 模式下事件可能乱序到达二分插入能保证调度队列始终有序。这也是为什么注释中写着events can arrive out of order in a realtime context。实战结合分页加载的完整模式把上述 API 组装成一套可用的分页回放方案典型的调用序列如下import { Replayer } from rrweb/replay; // 1. 先用第一页数据含 Meta 与 FullSnapshot初始化回放器 const replayer new Replayer(firstPageEvents, { liveMode: false, }); // 2. 开始播放 replayer.play(); // 3. 监听进度事件按需拉取下一页并追加 replayer.on(resize, () { /* 页面尺寸变化 */ }); async function loadMore(pageNo) { const events await fetch(/api/session/events?page${pageNo}).then((r) r.json()); for (const event of events) { replayer.addEvent(event); } }需要注意的实践要点首页数据必须包含快照第一页应包含Meta事件与FullSnapshot因为addEvent只负责追加增量不具备从零重建页面的能力追加时间灵活可在回放开始前批量预取追加也可在播放中、暂停中追加三种状态下状态机都能正确处理若要实现滚到哪播到哪结合replayer.getCurrentTime()与播放进度事件判断何时触发下一页请求即可直播场景协同若使用实时录制回放liveMode: true并调用startLive()addEvent依旧适用可参考文档 实时模式live mode 配合使用压缩解包如果录制端使用了 packer 压缩追加的事件可能以字符串形式存在此时需在Replayer配置中提供unpackFnaddEvent会先解包再入队。测试用例佐证仓库中的集成测试验证了addEvent在真实回放环境下的行为。packages/rrweb/test/replayer.test.ts#L949-L959 的用例replays same timestamp events in correct order (with addAction)模拟了分页场景先用events.slice(0, events.length - 2)初始化并播放再通过两次addEvent追加剩余两条事件最终断言 DOM 快照与全量加载的结果一致。这个用例直接证明了addEvent追加的数据与初始数据能无缝衔接、按正确顺序回放是本文所述方案最直接的验证依据。小结大数据量回放时采用分页 Replayer.addEvent增量追加可显著降低首屏网络开销与等待时间addEvent接受单条eventWithTime也支持经unpackFn解包的字符串调用后由状态机按时间戳二分插入事件数组自动维护回放序列的有序性早于当前播放进度的事件立即同步生效未来事件则挂入Timer按delay调度鼠标移动等特殊事件的时间戳会被addDelay精确还原无论播放、暂停还是 live 模式addEvent均可安全调用配合进度监听即可实现边播边加载的流畅分页体验。相关源码与文档入口实现 packages/rrweb/src/replay/index.ts、状态机 packages/rrweb/src/replay/machine.ts、调度器 packages/rrweb/src/replay/timer.ts、包入口 packages/replay/src/index.ts、验证用例 packages/rrweb/test/replayer.test.ts。【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
rrweb 异步分页加载与回放实战深入解析 Replayer.addEvent 的事件追加机制【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb当录制的会话数据体积较大时一次性将全部事件加载到回放页面会带来显著的网络开销与白屏等待时间。rrweb 提供了极简的Replayer.addEventAPI允许开发者按需分页加载数据并增量追加到正在运行的回放实例中由回放引擎自动处理事件间的时间关系。读完本文你将掌握基于addEvent实现异步分页回放的标准姿势并理解其背后状态机按时间戳插入、延迟调度与 live 模式协同的完整原理。为什么需要异步加载事件rrweb 的录制产物是一串带时间戳的事件数组eventWithTime[]每条事件都记录了 DOM 变更、交互行为、滚动位置等快照增量。当录制时间很长时事件总量可能达到数万甚至数十万条首屏加载开销大将完整数据一次性拉取到浏览器传输耗时和解析耗时都会明显拖慢回放页面的初始化等待时间长用户在数据完全到达之前无法看到任何内容体验与加载中无异资源浪费用户可能只查看片段全量数据并不总是必要。更合理的方案是分页pagination先加载第一条快照Meta 事件 FullSnapshot与一小段增量事件让回放先跑起来再随着播放进度逐步异步拉取后续页面的事件并追加给回放器。rrweb 官方文档 异步加载数据 给出的正是这一思路的最小实现。核心 APIReplayer.addEventrrweb 中用于实现异步加载数据的 API 非常简单直观来自回放器类Replayer的公开方法addEvent只需调用它传入新的数据rrweb 就会自动处理其中的时间关系以最恰当的方式进行回放。追加单个事件import { Replayer } from rrweb/replay; const replayer new Replayer(events); replayer.addEvent(NEW_EVENT);NEW_EVENT是任意一条后续加载到的eventWithTime事件。在真实分页场景中它通常来自你向后端发起的下一页数据请求的响应。循环追加多个事件如果需要异步加载多个数据只需循环调用即可import { Replayer } from rrweb/replay; const replayer new Replayer(events); for (const event of NEW_EVENTS) { replayer.addEvent(event); }代码层面只多了三行但这条循环背后的行为值得注意批量追加时并不要求传入的事件严格按时间递增。由于addEvent内部会按时间戳做有序插入下文详述乱序到达的事件也会被正确地排进回放序列。引入路径说明原文档示例使用rrweb/replay包名它对应仓库中的 packages/replay该包将Replayer从rrweb重新导出并附带回放所需的样式import { Replayer } from rrweb/replay; import rrweb/replay/dist/style.css;在 monorepo 内部Replayer的直接实现位于 packages/rrweb/src/replay/index.ts因此你同样可以直接从rrweb导入。addEvent 的底层实现从入口到状态机addEvent之所以自动处理时间关系是因为它背后串起了三个核心模块Replayer实例方法、基于 XState 的播放状态机machine.ts以及事件调度器Timertimer.ts。入口方法类型归一化与异步投递packages/rrweb/src/replay/index.ts#L572-L582 中addEvent的实现如下public addEvent(rawEvent: eventWithTime | string) { const event this.config.unpackFn ? this.config.unpackFn(rawEvent as string) : (rawEvent as eventWithTime); if (indicatesTouchDevice(event)) { this.mouse.classList.add(touch-device); } void Promise.resolve().then(() this.service.send({ type: ADD_EVENT, payload: { event } }), ); }从源码可以提炼出三个设计要点支持字符串入参rawEvent既可以是对象也可以是字符串。当配置了unpackFn例如配合 rrweb packer 插件的解包函数时字符串会先被解包成结构化事件再进行后续处理触屏设备标记如果追加的事件表明当前是触屏设备indicatesTouchDevice回放器会自动为鼠标光标元素添加touch-device类保证光标渲染形态正确微任务异步投递addEvent通过Promise.resolve().then(...)把ADD_EVENT动作投递给状态机而不是同步执行。这意味着你在一次事件循环里连续调用多次addEvent会被统一收拢到下一轮微任务中依序处理天然避免了批处理时的重入问题。状态机三个状态统一响应 ADD_EVENT播放状态机packages/rrweb/src/replay/machine.ts定义了playing、paused、live三种状态而ADD_EVENT在三种状态下都能被响应playing态追加事件并继续播放target: playing, actions: [addEvent]paused态追加事件但保持暂停target: paused, actions: [addEvent]live态追加事件并维持直播模式target: live, actions: [addEvent]。也就是说无论回放器当前处于播放、暂停还是直播状态addEvent都能安全生效这正是它适合边播边拉数据场景的根本原因。测试 packages/rrweb/test/replayer.test.ts#L905-L935 也验证了在liveMode: true下调用startLive()后继续addEvent回放器不会误触发Finish事件。addEvent action按时间戳二分插入状态机中真正干活的addEventaction 位于 packages/rrweb/src/replay/machine.ts#L238-L279核心逻辑如下addEvent: assign((ctx, machineEvent) { const { baselineTime, timer, events } ctx; if (machineEvent.type ADD_EVENT) { const { event } machineEvent.payload; addDelay(event, baselineTime); let end events.length - 1; if (!events[end] || events[end].timestamp event.timestamp) { // fast track events.push(event); } else { // 二分查找插入位置保证 events 始终按 timestamp 升序 let insertionIndex -1; let start 0; while (start end) { const mid Math.floor((start end) / 2); if (events[mid].timestamp event.timestamp) { start mid 1; } else { end mid - 1; } } if (insertionIndex -1) { insertionIndex start; } events.splice(insertionIndex, 0, event); } const isSync event.timestamp baselineTime; const castFn getCastFn(event, isSync); if (isSync) { castFn(); // 落后于当前进度的事件立即同步回放 } else if (timer.isActive()) { timer.addAction({ // 未来事件挂入定时器按 delay 调度 doAction: () { castFn(); }, delay: event.delay!, }); } } return { ...ctx, events }; }),关键行为有三条有序插入若新事件的时间戳不早于当前最后一个事件fast track 快路径直接push否则通过二分查找找到插入位置执行splice保证事件数组始终按timestamp升序。这就是乱序到达的事件也能被正确回放的原理追加即算延迟addDelay会在追加时立刻根据事件时间戳与当前baselineTime基线时间计算出event.delay同步/异步分流时间戳早于基线时间的事件即应该已经播过的部分直接同步执行castFn立即生效时间戳在未来的事件则通过timer.addAction挂入调度队列等待Timer触发。另外若Timer尚未激活例如播放前批量 addEvent事件只会进入数组排队不会提前触发。Timer 与 addDelay时间关系如何被自动处理Timer类packages/rrweb/src/replay/timer.ts维护一个按delay排序的动作队列并在每一帧rafCheck中取出timeOffset action.delay的动作执行从而把事件时间戳翻译成播放时钟上的触发时刻。addDelay函数timer.ts#L119-L137对鼠标移动事件做了专门处理由于 mousemove 在录制端经过节流合并event.timestamp并不是真实移动时刻因此需要遍历data.positions[0].timeOffset还原首个采样点的真实时间戳后再计算延迟if ( event.type EventType.IncrementalSnapshot event.data.source IncrementalSource.MouseMove event.data.positions event.data.positions.length ) { const firstOffset event.data.positions[0].timeOffset; const firstTimestamp event.timestamp firstOffset; // timeOffset 为负偏移 event.delay firstTimestamp - baselineTime; return firstTimestamp - baselineTime; } event.delay event.timestamp - baselineTime;此外Timer.addAction同样使用fast track 二分插入timer.ts#L28-L44且在实时场景live 模式下事件可能乱序到达二分插入能保证调度队列始终有序。这也是为什么注释中写着events can arrive out of order in a realtime context。实战结合分页加载的完整模式把上述 API 组装成一套可用的分页回放方案典型的调用序列如下import { Replayer } from rrweb/replay; // 1. 先用第一页数据含 Meta 与 FullSnapshot初始化回放器 const replayer new Replayer(firstPageEvents, { liveMode: false, }); // 2. 开始播放 replayer.play(); // 3. 监听进度事件按需拉取下一页并追加 replayer.on(resize, () { /* 页面尺寸变化 */ }); async function loadMore(pageNo) { const events await fetch(/api/session/events?page${pageNo}).then((r) r.json()); for (const event of events) { replayer.addEvent(event); } }需要注意的实践要点首页数据必须包含快照第一页应包含Meta事件与FullSnapshot因为addEvent只负责追加增量不具备从零重建页面的能力追加时间灵活可在回放开始前批量预取追加也可在播放中、暂停中追加三种状态下状态机都能正确处理若要实现滚到哪播到哪结合replayer.getCurrentTime()与播放进度事件判断何时触发下一页请求即可直播场景协同若使用实时录制回放liveMode: true并调用startLive()addEvent依旧适用可参考文档 实时模式live mode 配合使用压缩解包如果录制端使用了 packer 压缩追加的事件可能以字符串形式存在此时需在Replayer配置中提供unpackFnaddEvent会先解包再入队。测试用例佐证仓库中的集成测试验证了addEvent在真实回放环境下的行为。packages/rrweb/test/replayer.test.ts#L949-L959 的用例replays same timestamp events in correct order (with addAction)模拟了分页场景先用events.slice(0, events.length - 2)初始化并播放再通过两次addEvent追加剩余两条事件最终断言 DOM 快照与全量加载的结果一致。这个用例直接证明了addEvent追加的数据与初始数据能无缝衔接、按正确顺序回放是本文所述方案最直接的验证依据。小结大数据量回放时采用分页 Replayer.addEvent增量追加可显著降低首屏网络开销与等待时间addEvent接受单条eventWithTime也支持经unpackFn解包的字符串调用后由状态机按时间戳二分插入事件数组自动维护回放序列的有序性早于当前播放进度的事件立即同步生效未来事件则挂入Timer按delay调度鼠标移动等特殊事件的时间戳会被addDelay精确还原无论播放、暂停还是 live 模式addEvent均可安全调用配合进度监听即可实现边播边加载的流畅分页体验。相关源码与文档入口实现 packages/rrweb/src/replay/index.ts、状态机 packages/rrweb/src/replay/machine.ts、调度器 packages/rrweb/src/replay/timer.ts、包入口 packages/replay/src/index.ts、验证用例 packages/rrweb/test/replayer.test.ts。【免费下载链接】rrwebrecord and replay the web项目地址: https://gitcode.com/gh_mirrors/rr/rrweb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
