Univer 调试插件 univerjs/debugger为电子表格引擎打造开发期诊断工具箱【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer本文基于 Univer 仓库中的 common/debugger/README.md 及其配套源码系统讲解univerjs/debugger调试插件的定位、安装方式、全部配置项含义、插件生命周期内的控制器装配逻辑以及它在开发演示、FPS 性能监控和 Playwright E2E 自动化测试三类场景中的具体用法。读完后你可以在自己的 Univer 应用中注册该插件、按需裁剪其功能开关并理解 E2E 测试平台所依赖的window.E2EControllerAPI是如何被这个插件提供出来的。一、插件定位与重要约束univerjs/debugger是 Univer 仓库内置的一个独立子包位于 common/debugger官方 README 对其定义非常直接This plugin provides a lot of utilities to help you debug Univer.也就是说它不是一个面向最终用户的功能模块而是面向 Univer 二次开发者与测试平台的开发期工具集。README 在开头用醒目警告标出第一条使用约束⚠️ CAUTION: NEVER use this plugin in your production environment!这一约束在源码中也有对应体现插件会向全局窗口对象挂载调试 API、注册演示组件、打开屏幕录制等浏览器能力且会引入univerjs/mockdata等演示数据依赖见 package.json 的dependenciesuniverjs/core、univerjs/design、univerjs/engine-render、univerjs/sheets、univerjs/ui、univerjs/watermark、univerjs/mockdata等因此只应出现在开发环境与自动化测试环境中。包级元信息来自 README 的 Package Overview 表如下项值包名univerjs/debuggerUMD 命名空间UniverDebugger许可证Apache-2.0见 package.json是否包含 CSS是入口 src/index.ts 首行import ./global.css是否内置 i18n否文案通过配置项localeLoader动态加载版本仓库内为1.0.0-beta.2且private: true随 monorepo 统一发布从 package.json 的exports字段可以看到该包直接以源码./src/index.ts作为入口.: ./src/index.ts,./*: ./src/*在 Univer 的 pnpm workspace 内由构建工具直接消费 TypeScript 源码。二、安装与注册README 给出的安装命令# Using npm npm install univerjs/debugger # Using pnpm pnpm add univerjs/debugger2.1 最小注册示例插件导出面非常收敛src/index.ts 只导出两样东西export type { IUniverDebuggerConfig, UniverDebuggerLocaleLoader } from ./config/config; export { UniverDebuggerPlugin } from ./plugin;因此注册时只需引入UniverDebuggerPlugin并传入配置对象。仓库内的真实用法位于 sheets 示例入口 examples/src/sheets/main.ts// If we are running in e2e platform, we should immediately register the debugger plugin. if (IS_E2E) { univer.registerPlugin(UniverDebuggerPlugin, { fab: false, fabEntryUnitType: UniverInstanceType.UNIVER_SHEET, localeLoader: loadDebuggerLocale, performanceMonitor: { enabled: false, }, }); }这段代码透露了三个关键实践点按运行环境条件注册示例通过process.env.IS_E2E判断当前是否运行在 E2E 测试平台是则注册插件。这与生产环境禁用的警告直接对应——插件只在测试态挂载。localeLoader是必传项类型为UniverDebuggerLocaleLoader签名是(locale: LocaleType) ILanguagePack | PromiseILanguagePack定义于 config/config.ts。仓库提供的实现是univerjs/mockdata导出的loadDebuggerLocale见 common/mockdata/src/index.ts。E2E 场景下关闭交互类功能fab: false隐藏浮动按钮、performanceMonitor.enabled: false关掉 FPS 监控因为无头浏览器里这些界面元素没有意义只需要保留挂在window上的 E2E API。2.2 运行环境前提从 package.json 的peerDependencies看该插件要求宿主应用具备react: ^16.9.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rcFAB 按钮是 React 组件见 views/Fab.tsxrxjs: 7.0.0性能监控等控制器大量使用 RxJS 响应式链路。三、配置项全解IUniverDebuggerConfig全部配置类型定义在 config/config.tsexport interface IUniverDebuggerConfig { menu?: MenuConfig; fab?: boolean; fabEntryUnitType: UniverInstanceType; localeLoader: UniverDebuggerLocaleLoader; performanceMonitor?: { enabled: boolean; }; }逐项说明配置项类型默认值作用menuMenuConfig来自univerjs/ui无注入 Univer 菜单系统会 merge 进全局menu配置fabbooleantrue见defaultPluginConfig是否注册右下角浮动按钮FAB它是调试菜单的入口fabEntryUnitTypeUniverInstanceType必传无默认值FAB 下拉菜单按入口单元类型裁剪调试项集合SHEET / DOC / SLIDE / BASE 各不同localeLoader函数必传无默认值按LocaleType懒加载调试面板文案包performanceMonitor.enabledbooleantrue见defaultPluginConfig是否装配 FPS 监控控制器默认值由defaultPluginConfig给出config/config.tsexport const defaultPluginConfig: PickIUniverDebuggerConfig, fab | performanceMonitor { fab: true, performanceMonitor: { enabled: true, }, };注意这个默认值对象只声明了fab和performanceMonitor两个字段menu、fabEntryUnitType、localeLoader不在其中——后两者除menu外属于调用方必须显式提供的必填语义配置。3.1 配置的写入与读取流程插件构造函数plugin.ts对配置做了两路分发const { menu, ...rest } merge({}, defaultPluginConfig, this._config); if (menu) { this._configService.setConfig(menu, menu, { merge: true }); } this._configService.setConfig(DEBUGGER_PLUGIN_CONFIG_KEY, rest);menu被单独摘出来以merge: true方式并入 Univer 全局menu配置保证调试菜单与其他插件贡献的菜单项共存其余配置写入键DEBUGGER_PLUGIN_CONFIG_KEY值为字符串debugger.config同时有对应的configSymbol。后续DebuggerController、Fab组件都通过IConfigService.getConfig(DEBUGGER_PLUGIN_CONFIG_KEY)回读这份配置见 debugger.controller.ts 与 Fab.tsx。这种合并默认值 → 写入配置服务 → 各控制器按需回读的模式与 Univer 其他插件的配置管理方式保持一致。四、插件生命周期与控制器装配UniverDebuggerPlugin继承自univerjs/core的Plugin基类plugin.ts静态标识pluginName UNIVER_DEBUGGER_PLUGIN版本号直接取自package.json。其生命周期把四个控制器分阶段装配进依赖注入容器override onStarting(): void { const dependencies: Dependency[] [ [DebuggerController], [ComponentsController], [E2EController], ]; if (this._config.performanceMonitor?.enabled ! false) { dependencies.push([PerformanceMonitorController]); } registerDependencies(this._injector, dependencies); touchDependencies(this._injector, [[E2EController]]); } override onReady(): void { touchDependencies(this._injector, [[ComponentsController], [DebuggerController]]); } override onRendered(): void { touchDependencies(this._injector, [[PerformanceMonitorController]]); }对应关系如下生命周期动作说明onStarting注册 4 个控制器性能监控按配置开关立即触碰E2EController保证window.E2EControllerAPI尽早可用onReady触碰ComponentsController、DebuggerController此时 UI 宿主容器已就绪可注册演示组件与 FABonRendered触碰PerformanceMonitorControllerFPS 监控需要等渲染引擎完成首帧后才订阅渲染循环这里有一个值得注意的配置判断细节性能监控的跳过条件是enabled ! false时才注册即只有显式传false才会禁用与默认值true形成呼应而Fab组件渲染 FPS 占位符时的判断是performanceMonitor?.enabled为真值才显示Fab.tsx。四个控制器各自承担的职责正是这个插件调试工具集的四大板块下面逐一展开。五、FAB 浮动按钮按单元类型裁剪的调试菜单DebuggerControllercontrollers/debugger.controller.ts做两件事若配置fab为真向BuiltInUIPart.GLOBAL注册全局组件Fab并让它的销毁跟随控制器销毁disposeWithMethis.disposeWithMe( this._uiPartsService.registerComponent(BuiltInUIPart.GLOBAL, () connectInjector(Fab, this._injector)) );向注入器添加RecordController命令录制器见第八节。Fab组件views/Fab.tsx渲染在页面右下角data-u-compdebugger-fab核心是一个DropdownMenu下拉菜单。菜单项集合根据fabEntryUnitType裁剪SHEET 类型完整调试项locale、RTL、暗色模式、主题、水印之后是通知notification、消息message、对话框dialog、侧边栏sidebar、浮层 DOMfloatingDom、单元格内容读取cellContent、多实例管理units、快照snapshot、可编辑切换editable、当前用户user、销毁实例disposeDOC 类型全局项 通知/消息/对话框/侧边栏 快照/可编辑/销毁 浮层 DOMSLIDE / BASE 类型lightweight仅 locale、RTL、暗色模式、主题、水印五项。这些调试项分别由 views 目录下的 15 个 hook 文件实现use-locale.ts、use-rtl.ts、use-dark-mode.ts、use-theme.ts、use-watermark.ts、use-notification.ts、use-message.ts、use-dialog.ts、use-sidebar.ts、use-floating-dom.ts、use-cell-content.ts、use-units.ts、use-snapshot.ts、use-editable.ts、use-user.ts、use-dispose.ts。从源码结构看每个 hook 封装读取/触发某个 Univer 服务的调试动作例如use-snapshot用于读取当前文档快照、use-units用于多实例切换、use-dispose用于销毁当前 Univer 实例——它们本质上是把 Univer 服务层的 API 暴露成一键式 UI 操作方便开发者在浏览器里直接触发和观察行为。当performanceMonitor.enabled为真时FAB 按钮下方还会渲染一个span>lifecycleService.subscribeWithPrevious() .pipe(filter((stage) stage LifecycleStages.Rendered), take(1)) .subscribe(() this._listenDocumentTypeChange());跟随焦点单元订阅IUniverInstanceService.focused$当用户切换聚焦的工作簿/文档单元时先取消旧订阅_disposeCurrentObserver再对新单元建立监听保证监控目标始终跟随当前激活的渲染单元。订阅渲染引擎帧事件通过IRenderManagerService.getRenderUnitById(unitId)拿到渲染单元订阅其engine.endFrame$事件每帧结束时读取engine.getFps()并四舍五入写入 FAB 下的[data-u-compdebugger-fps]元素this._currentUnitSub engine.endFrame$.subscribe(() { if (!this._containerElement) { this._containerElement document.querySelector([data-u-compdebugger-fps]); } else { this._containerElement.textContent FPS: ${Math.round(engine.getFps()).toString()}; } });注意document.querySelector只在首帧执行一次做缓存后续帧直接改写textContent避免每帧触发 DOM 查询。dispose()时同步退订避免内存泄漏。这套实现展示了在 Univer 上做自定义性能监控的标准姿势LifecycleService 定阶段 → RenderManagerService 拿引擎 → 订阅endFrame$。你在自己项目里做帧率、脏矩形面积等监控时可以参照这条链路。七、E2E 平台桥window.E2EControllerAPIE2EControllercontrollers/e2e/e2e.controller.ts是调试插件中最非 UI的部分——它把一组测试辅助 API 挂到window.E2EControllerAPI供 Playwright 等外部测试框架通过page.evaluate调用。源码中的注释明确说明This interface is copied toe2e/e2e.d.ts. When you modify this interface, make sure the duplication is updated as well.即接口契约与仓库 e2e/e2e.d.ts 保持手工同步。公开的能力IE2EControllerAPI包括方法作用loadAndRelease(id, loadTimeout?, disposeTimeout?)创建一个e2e{id}工作簿、等待加载后销毁用于实例创建/销毁的内存泄漏类测试loadDefaultSheet(loadTimeout?)载入默认工作簿 fixturedata/default-sheet.tsloadDemoSheet()载入univerjs/mockdata中的DEFAULT_WORKBOOK_DATA_DEMO演示大表loadMergeCellSheet()载入演示数据中的合并单元格表sheet-0003loadDefaultStyleSheet()载入默认样式的演示工作簿loadDefaultDoc(loadTimeout?)/loadDocLayoutFixture(flavor, loadTimeout?)载入默认文档 fixture或按DocumentFlavorTRADITIONAL / MODERN构建特定布局文档setDarkMode(darkMode)通过ThemeService切换暗色模式disposeCurrSheetUnit(disposeTimeout?)销毁当前聚焦的电子表格单元并等待disposeUniver()调用window.univer.dispose()并清空window.univer/window.univerAPIscrollAndClearCanvas(canvas, pixelRatio, scrollRenderInfos, dirtyBounds)把渲染引擎的scrollAndClearCanvas能力暴露给测试端配合视觉对比测试默认超时常量AWAIT_LOADING_TIMEOUT与AWAIT_DISPOSING_TIMEOUT均为 5000ms。这与仓库根目录 examples/src/sheets/main.ts 中const IS_E2E: boolean !!process.env.IS_E2E;的构建约定形成闭环E2E 构建产物中注册调试插件后测试脚本即可驱动一个干净、可复现的 Univer 环境。仓库 e2e 目录下的用例如 e2e/disposing/disposing.spec.ts、e2e/memory/memory.spec.ts、e2e/visual-comparison正是消费这套 API 的测试代码其中内存测试与 dispose 测试直接依赖loadAndRelease/disposeUniver提供的加载—等待—销毁能力。插件的getDebuggerController()方法plugin.ts则允许宿主在需要时从插件实例同步取出DebuggerController进一步定制调试行为。八、演示组件注册与本地录制工具8.1 ComponentsController演示组件注册表ComponentsControllercontrollers/components.controller.ts通过ComponentManager注册了一批可在菜单系统中引用的演示组件([ImageDemo, ImageDemo], [RangeLoading, RangeLoading], [FloatButton, FloatButton], [AIButton, AIButton], [WATERMARK_PANEL, WatermarkPanel], [WATERMARK_PANEL_FOOTER, WatermarkPanelFooter])对应组件源码在 components 目录Image.tsx、RangeLoading.tsx、FloatButton.tsx等水印面板则在 views/watermark 下。从源码结构看该文件还保留了两段被注释的注册代码VueComponent.vueframework: vue3与 Web Componentframework: web-component说明该注册机制设计上支持 React 之外的框架组件接入与 Univer 的 UI 适配层如ui-adapter-vue3、ui-adapter-web-component能力呼应。8.2 RecordController屏幕录制与命令录制RecordControllercontrollers/local-save/record.controller.ts提供两个开发者向的工具方法record()返回一个 RxJSObservable调用navigator.mediaDevices.getDisplayMedia请求屏幕捕获用MediaRecorder优先video/webm; codecsvp9录制dataavailable收集分片stop时拼装成Blob发出{ type: finish, data }。典型用途是本地复现 bug 时录屏便于提交缺陷报告startSaveCommands()挂到ICommandService.beforeCommandExecuted钩子上按[秒级时间戳, 命令 id, 命令类型, JSON 参数]四元组记录执行序列调用返回的清理函数可取回完整列表。这是排查多步操作后状态错乱类问题的利器——把用户操作序列完整回放出来。这两个方法属于命令式 API通过注入器获取控制器后调用并非开箱即用的 UI适合开发者在控制台或自定义调试面板中按需启用。九、使用建议与边界结合 README 警告与源码实现给出落地建议只在开发/测试环境注册E2E 场景推荐照抄 examples/src/sheets/main.ts 的写法fab: falseperformanceMonitor.enabled: false只保留 E2E API 桥减小运行时开销本地开发调试保持默认配置fab: true FPS 监控开启即可获得右下角调试菜单与帧率显示用fabEntryUnitType选择与主工作单元匹配的类型以获得最完整的调试项必填配置不可省fabEntryUnitType与localeLoader无默认值localeLoader可直接复用univerjs/mockdata导出的loadDebuggerLocale能力边界该插件不提供 i18n 静态文案README 标注 Contains i18n locales 为否、不做服务端能力、也不承诺 API 稳定性包标记private: true以 monorepo 版本1.0.0-beta.2随整体 beta 节奏演进改动 E2E 接口需同步若你 fork 仓库并扩展IE2EControllerAPI源码注释明确要求同步更新 e2e/e2e.d.ts否则 Playwright 侧类型将失配。十、小结univerjs/debugger用一组轻量的控制器把 Univer 各服务层能力生命周期、渲染引擎、配置服务、菜单/组件系统、命令服务聚合成一个开发期诊断面FAB 调试菜单负责一键触发服务FPS 监控展示渲染链路健康度E2E 桥提供可编程的测试环境录制工具则负责操作与画面的留证。理解它的内部装配方式plugin.ts的生命周期分发、IConfigService的配置读写也等于掌握了在 Univer 中自建一个调试/诊断插件的完整模板。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考