前端可观测性开发工具【免费下载链接】rrwebrecord and replay the web项目地址https://gitcode.com/gh_mirrors/rr/rrweb点击查看免费下载rrweb/types是 rrweb 在 2.0 时代从核心仓库中拆分出的共享类型包集中定义了录制与回放所依赖的事件契约、增量数据类型与插件接口。本篇文章以 packages/types/CHANGELOG.md 为主线结合仓库源码系统梳理该包的诞生背景、事件契约全景、2.0 大版本的破坏性变更以及 2.1.x 阶段的关键能力演进帮助读者理解 rrweb 事件格式的来龙去脉并掌握升级与迁移的要点。一、包的定位为什么需要一个独立的共享类型包在 rrweb 2.0 之前事件类型event types与录制类型recorder types散落在各个包中跨包引用类型时常常需要深挖内部路径。2.0 版本通过 PR #1031对应 changelog 2.0.0 的 Major Changes将共享的 rrweb 事件类型和录制类型集中迁移到新的rrweb/types包中从而让rrweb、rrweb-snapshot、rrweb-replay、rrdom以及各类插件包都能从同一处导入类型避免重复定义和循环依赖为第三方插件作者提供稳定的类型契约如RecordPlugin、各增量源的数据结构让类型与运行时代码解耦rrweb/types本身几乎不包含运行时逻辑从 packages/types/src/index.ts 的源码结构看该文件从头到尾都是类型与枚举的导出这也解释了为什么它可以在type: module下以极小的体积被任何包引用。从仓库的依赖关系可以印证这一地位rrweb、rrweb-snapshot、rrweb-replay、rrdom、rrdom-nodejs、packer、browser-client、all以及网络插件包均在其 package.json 中以rrweb/types: ^2.1.5或相近版本声明依赖。而在 packages/rrweb/src/index.ts 中主包会从rrweb/types导入并重新导出大量公开类型使用者通过import rrweb from rrweb即可获得类型与实现无需单独安装类型包即可获得类型提示。二、事件类型契约全景从源码看 types 包的核心资产rrweb/types的核心价值在于它完整定义了 rrweb 的事件序列化格式。以当前仓库 packages/types/src/index.ts 为证契约主要分为以下几层。1. 顶层事件枚举与事件结构EventType枚举packages/types/src/index.ts#L1-L10定义了八类顶层事件export enum EventType { DomContentLoaded, Load, FullSnapshot, IncrementalSnapshot, Meta, Custom, Plugin, Asset, }每类事件对应一个带type判别字段的结构体最终通过eventWithoutTime联合类型统一再叠加timestamp与可选delay形成带时间戳的eventWithTimepackages/types/src/index.ts#L247-L250export type eventWithTime eventWithoutTime { timestamp: number; delay?: number; };eventWithTime是录制端输出的标准单位也是回放端、rrweb/packer见 packages/packer/src/pack.ts 的PackFn (event: eventWithTime) string与存储层共同依赖的数据形状。2. 增量事件源IncrementalSource 与 incrementalData页面交互过程中的动态变化通过IncrementalSnapshot事件承载其data由incrementalData联合类型定义packages/types/src/index.ts#L215-L229包含 15 种来源枚举IncrementalSourcepackages/types/src/index.ts#L134-L152覆盖了 DOM 变更、鼠标/触摸/拖拽、滚动、视口缩放、输入、媒体交互、样式表规则与声明、Canvas 变更、字体、选区、AdoptedStyleSheet、自定义元素等全部录制维度。每种来源都定义了独立的xxxData结构例如mutationDataDOM 增删改mouseInteractionData点击、聚焦、上下文菜单等mediaInteractionData播放、暂停、音量、倍速等canvasMutationData2D/WebGL 绘制调用styleSheetRuleData/styleDeclarationDataCSSOM 变更3. 录制回调与采样配置hooksParampackages/types/src/index.ts#L330-L344定义了录制端向外部暴露的各类回调钩子SamplingStrategypackages/types/src/index.ts#L261-L295则规定了采样策略的类型形状如mousemove的节流阈值、input: all | last、canvas: all | number等是rrweb.record()配置项的类型来源。这些类型正是 2.0 拆分时从主包迁入rrweb/types的录制类型主体。三、2.0.0 大版本破坏性变更与产物分发体系重构changelog 的 2.0.0 条目集中记录了两个 Major Changes这是理解该包乃至整个 rrweb 2.0 生态升级成本的关键。1. 产物文件命名、路径与扩展名全面调整PR #1497这是 rrweb 2.0 最容易被忽略的破坏性变更分布式文件的文件名、路径和扩展名都变了。changelog 原文明确提示如果直接引用分布式文件或类型必须更新路径/文件名例如从rrweb/typings/...或rrdom/es导入的写法不再有效若通过import rrweb from rrweb使用则感知不到这一变化若通过script标签直接引入需要改用.umd.cjs文件所有.js文件现在都是 ES 模块适用于现代浏览器、Node.js 及支持 ESM 的打包器所有 npm 包同时提供.cjs与.umd.cjs.umd.cjs是打包为单文件的 CommonJS 产物类似旧版.js的浏览器用法.cjs供旧版 Node.js 使用。从当前 packages/types/package.json 可以清晰看到这套体系的落地形态{ type: module, main: ./dist/types.umd.cjs, module: ./dist/types.js, unpkg: ./dist/types.umd.cjs, jsdelivr: ./umd/types.js, typings: dist/index.d.ts, exports: { .: { import: { types: ./dist/index.d.ts, default: ./dist/types.js }, require: { types: ./dist/index.d.cts, default: ./dist/types.umd.cjs } } }, files: [umd, dist, package.json] }要点解读import条件对应 ESM 产物dist/types.jsrequire条件对应 CommonJS 单文件产物dist/types.umd.cjs并分别提供.d.ts与.d.cts类型声明exports字段锁定了包的唯一入口禁止深路径导入如rrweb/types/dist/xxx这也是 PR #1497 所说的package.json 的main和exports字段决定了可用文件files只发布umd、dist与package.json其中umd目录是 PR #1704 补充的在dist之外额外提供带.js扩展名的 UMD 文件jsdelivr指向./umd/types.js避免package.json 声明dist下所有.js都是模块的预期被 UMD 文件破坏。升级提示如果你的构建链路或 CDN 直接引用了旧路径如rrweb/typings/...升级 2.0 后必须按上述exports映射调整如果只是import rrweb from rrweb则无需改动。2. 类型归属调整特定类型迁移到其他包PR #1031 / #1497changelog 明确提到部分特定类型被导出到新的包中例如PlayerMachineState与SpeedMachineState现在从rrweb/replay导出。这意味着回放相关状态机类型不再属于rrweb/types需要从回放包引入使用rrweb/types时应只引用事件与录制契约相关类型避免继续依赖旧的集中式 typings 入口。3. 工程细节TypeScript 4.9.5 与 NodeNext 兼容PR #1287 / #1369PR #1287 将仓库全部项目升级到 TypeScript 4.9.5rrweb/types的类型声明也随之上限对齐PR #1369 修复了moduleResolution: NodeNext下的类型错误这一点对使用 Node.js 原生 ESM 解析策略NodeNext/Node16的消费者尤为重要——如果升级后出现类型解析错误请检查是否已使用包含exports字段映射的较新版本2.0.0 正式版起已修复。四、事件契约的关键能力演进2.0 系列 Minor 变更除了破坏性重构2.0 阶段还通过多个 Minor 变更扩充了事件契约本身这些都可以在当前源码中得到印证。1. pointerType区分鼠标、触控笔与触摸PR #1129点击类事件新增.pointerType属性用于区分pen、mouse、touch三类指针来源对应 PointerEvent.pointerType 的取值。changelog 特别说明没有新增 PenDown/PenUp 事件笔事件可以通过MouseDown/MouseUp pointerTypepen组合识别。在类型层packages/types/src/index.ts#L446-L450 定义了PointerTypes枚举Mouse、Pen、Touch而mouseInteractionParampackages/types/src/index.ts#L496-L502将pointerType?: PointerTypes声明为可选字段以保持向后兼容。在实现层packages/rrweb/src/record/observer.ts#L219-L275 展示了完整的映射逻辑从原生事件读取pointerType字符串映射到PointerTypes枚举对触摸事件还会维护当前指针类型状态在后续移动/交互事件中沿用该状态最后仅在pointerType ! null时写入事件对象。这条链路说明录制端生成的增量事件中pointerType是可选但尽量填充的增强字段回放端消费时需做空值兼容。2. 顶层dialog组件支持PR #1503PR #1503 为顶层dialog组件提供支持修复了 #1381。其类型落点在快照侧 packages/rrweb-snapshot/src/types.ts#L7-L22 定义了DialogAttributesexport type DialogAttributes { open: string; rr_open_mode: modal | non-modal; // rr_open_mode_index?: number; // 预留用于按顺序回放多次 showModal() };rr_open_mode区分showModal()modal与show()/添加open属性non-modal两种打开方式注释中还预留了rr_open_mode_index字段用于未来按打开顺序回放多个 dialog。这与仓库中 dialog 相关的回放测试如 packages/rrweb/test/replay/dialog.test.ts 及其 图片快照 目录相互印证回放端会依据该属性重建 dialog 的打开状态与层级。3. 跨域 iframe 录制类型PR #1035PR #1035 为跨域 iframe 录制支持补充了类型定义。核心是ICrossOriginIframeMirror接口packages/types/src/index.ts#L297-L312它定义了父页面与跨域 iframe 之间节点 ID 的映射能力getId(iframe, remoteId, ...)将 iframe 内的远端节点 ID 映射为主文档 IDgetRemoteId(iframe, parentId, ...)反向映射回 iframe 内的 ID支持批量映射getIds/getRemoteIds与按 iframe 重置reset(iframe?)。实现侧packages/rrweb/src/record/cross-origin-iframe-mirror.ts 直接以import type { ICrossOriginIframeMirror } from rrweb/types引用该接口RecordPlugin.getMirror回调packages/types/src/index.ts#L322-L326也会向插件注入包含nodeMirror、crossOriginIframeMirror、crossOriginIframeStyleMirror三个镜像实例其中后两个即为跨域 iframe 场景而设。测试见 packages/rrweb/test/record/cross-origin-iframes.test.ts。4. mediaInteractionParam 新增 loopPR #1432PR #1432 为媒体交互参数补充loop字段。当前类型定义packages/types/src/index.ts#L649-L657export type mediaInteractionParam { type: MediaInteractions; id: number; currentTime?: number; volume?: number; muted?: boolean; loop?: boolean; playbackRate?: number; };录制端在 packages/rrweb/src/record/observer.ts#L1036-L1045 中从媒体元素解构currentTime, volume, muted, playbackRate, loop并写入事件对应地快照侧mediaAttributespackages/types/src/index.ts#L846-L865也声明了rr_mediaLoop?: boolean等序列化属性。这使得回放时可以精确还原循环播放的媒体状态。五、2.1.x 阶段插件契约与资产事件1. 网络插件类型进入共享包2.1.0PR #1689rrweb/types2.1.0 的核心变更是Add the network-plugin。从此版本起网络录制相关的类型正式纳入共享包当前源码packages/types/src/index.ts#L63-L123包含一整套网络事件契约NetworkInitiatorType资源发起类型联合涵盖audio、beacon、fetch、iframe、img、script、xmlhttprequest等 21 种取值NetworkRequest基于PerformanceEntry派生并补充method、status、requestHeaders、requestBody、responseHeaders、responseBody、isInitial等字段的网络请求结构NetworkRecordOptions插件的配置类型支持initiatorTypes按发起类型过滤、transformRequestFn请求转换、recordHeaders/recordBody布尔或分请求/响应细粒度控制、recordInitialRequests等NetworkEvent pluginEventNetworkData网络事件以插件事件EventType.Plugin的形式承载requests数组。实际插件 packages/plugins/rrweb-plugin-network-record 与 packages/plugins/rrweb-plugin-network-replay 均直接依赖rrweb/types见各自 package.json印证了共享类型为插件生态服务的设计意图。2. Asset 事件类型别名2.0.0 PatchPR #1833PR #1833 为 2.0 事件契约补充公开的 Asset 事件类型别名。源码中对应export type assetEvent { type: EventType.Asset; data: assetParam }; export type assetEventWithTime assetEvent { timestamp: number };assetParampackages/types/src/index.ts#L691-L703支持两种形态成功时携带url与payload如 Canvas 序列化参数或SerializedCssTextArg失败时携带failed: { status?, message }。EventType.Asset在 EventType 枚举 中同样可见用于承载全快照阶段资源图片、样式等的序列化结果或加载失败信息。3. 紧凑样式变更修复2.0.0 PatchPR #1268PR #1268 修复并优化了紧凑compact样式变更修复样式更新中包含作用于简写属性shorthand property的var()时的问题issue #1246进一步保证样式变更保持紧凑若字符串形式更短则回退到字符串方法记录。这一改动作用于styleSheetRuleParam/styleDeclarationParam相关的事件生成逻辑目标是控制增量事件体积属于不影响外部类型形状的内部优化。六、版本发布节奏与依赖联动从 changelog 可以还原rrweb/types的发布节奏版本类型主要内容2.0.0-alpha.5–7Patch仅跟随rrweb-snapshot变更2.0.0-alpha.8Minor新增pointerType2.0.0-alpha.9–12Patch跟随rrweb-snapshot2.0.0-alpha.13PatchmediaInteractionParam.loop、NodeNext 修复2.0.0-alpha.14–16Patch跟随rrweb-snapshot2.0.0-alpha.17Minor顶层dialog支持2.0.0-alpha.15/2.0.0Major产物分发体系重构、类型归属调整2.0.0 正式版Major包拆分落地、Asset 别名、样式压缩修复、TS 4.9.5、UMD 目录2.1.0Minor网络插件类型2.1.1–2.1.5—版本同步2.0.1 明确说明仅版本号提升以与其他包保持同步两个值得注意的规律alpha 阶段大量 Patch 版本只是跟随rrweb-snapshot——因为事件契约中的序列化节点类型serializedNodeWithId等定义在rrweb-snapshot中rrweb/types需要与之保持版本联动如 2.0.0 条目中的 Updated dependencies: rrweb-snapshot2.0.0-alpha.42.1.1–2.1.5 之间无实质变更属于 monorepo 内的版本对齐changesets批量发布机制所致网络插件相关类型在 2.1.0 已就位因此当前各包统一依赖^2.1.5是安全的。七、实践指南如何消费 rrweb/types安装与导入rrweb/types通常是作为rrweb等包的传递依赖被安装的一般无需显式安装若插件开发或自定义事件处理需要直接使用其类型可显式安装npm install --save-dev rrweb/types # 或 yarn add --dev rrweb/types导入方式ESM / 类型导入import type { eventWithTime, IncrementalSource, EventType } from rrweb/types; import { EventType, IncrementalSource } from rrweb/types; // 枚举可直接导入注意由于exports字段的限制不应使用rrweb/types/dist/...之类的深路径导入且event类型在源码中已被标记为deprecatedpackages/types/src/index.ts#L241-L245它是eventWithoutTime的同义词仅供内部使用新代码应直接使用eventWithoutTime或eventWithTime。典型使用场景自定义事件使用customEventT类型约束event.data.tag与payload插件开发基于RecordPluginTOptionspackages/types/src/index.ts#L314-L328编写录制插件实现observer、eventProcessor、getMirror等钩子类型契约保证插件与主包解耦事件处理管道以eventWithTime为输入编写存储、加密、压缩如 rrweb/packer或实时转发逻辑跨包类型复用在rrweb、rrweb-snapshot、回放包之间传递serializedNodeWithId等节点类型时统一从rrweb/types引入。升级到 2.x 的检查清单检查是否有直接引用rrweb/typings/...、rrdom/es等旧路径的代码按新版exports映射调整script直引场景改用.umd.cjs文件注意dist下.js均为 ESMPlayerMachineState、SpeedMachineState等回放状态类型改从rrweb/replay导入moduleResolution: NodeNext项目请升级到 2.0.0 及以上已修复类型解析消费增量事件时对新增的可选字段pointerType、loop等保持空值兼容以支持新旧录制数据并存。结语rrweb/types虽是一个只有类型、没有逻辑的包却是 rrweb 2.0 生态正常运转的契约基石它承载了从EventType/IncrementalSource到插件接口的完整事件模型其版本演进史packages/types/CHANGELOG.md浓缩了 rrweb 2.0 在分发体系、指针事件、dialog、跨域 iframe、媒体状态与插件生态上的全部关键变化。理解这个包就等于拿到了读懂 rrweb 事件流与进行二次开发的类型地图。赞分享前端可观测性开发工具【免费下载链接】rrwebrecord and replay the web项目地址https://gitcode.com/gh_mirrors/rr/rrweb点击查看免费下载相关推荐StaffML Vault 共享类型包staffml/vault-types技术指南Schema v1.0 类型契约与跨端集成实践StaffML Vault 共享类型包staffml/vault types技术指南Schema v1.0 类型契约与跨端集成实践 导读 staffm教育教程人工智能机器学习redux-saga/types 类型系统深度解析共享类型包的演进与 TypeScript 最佳实践redux saga/types 类型系统深度解析共享类型包的演进与 TypeScript 最佳实践 本文以 redux saga/types 包的变更日前端从0到1开发Android聊天应用基于Chateau框架的完整案例从0到1开发Android聊天应用基于Chateau框架的完整案例 Chateau是一个功能强大的Android聊天框架能够帮助开发者快速在任何Androi前端可观测性开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考