1. 从“univer”这个标题说起它到底是什么能解决什么问题第一次看到“univer”这个词很多人会下意识联想到“universe”或者“universal”觉得它可能是个大而全的东西。没错Univer 确实是一个野心不小的项目——它是一套开源的、面向电子表格与文档场景的前端渲染与协同引擎核心定位是让开发者能在浏览器里快速构建出类似在线表格、在线文档那样的应用。你可以把它理解成“前端表格与文档的底层操作系统”它把画布渲染、公式计算、协同编辑、插件扩展这些脏活累活都封装好了你只需要在上面搭业务界面就行。我最早接触 Univer 是因为团队要做一个轻量级的在线数据填报系统。当时评估过几条路线一是直接用开源表格组件但样式和交互定制成本极高二是自己基于 Canvas 从零画表格结果发现光是处理滚动、选区、公式就够喝一壶三是找一个成熟的引擎来二次开发。Univer 正好出现在视野里它用 Canvas 做渲染底座性能比 DOM 表格好很多而且插件架构让功能可以按需拼装不会一上来就背一个巨大的包。这篇文章适合谁看如果你正在做在线表格、在线文档、数据看板、低代码平台里的表格模块或者你单纯对“一个现代前端表格引擎是怎么设计出来的”感兴趣那这篇内容会对你有帮助。我会从整体设计思路、核心细节、实操过程、常见问题几个角度把 Univer 这套东西拆开讲清楚尽量让你看完能自己跑起来一个最小可用版本并且知道后面怎么扩展。需要提前说明的是Univer 本身是一个持续迭代的项目不同版本之间 API 会有变化。我下面提到的操作和配置是基于我实际用过的版本总结出来的通用思路具体到你的项目时建议先对照官方文档确认一下当前版本的接口签名。2. 整体设计与思路拆解为什么是 Canvas 插件架构2.1 为什么不用 DOM 表格而选 Canvas 渲染传统的前端表格方案比如各种 Grid 组件底层大多是 DOM 结构一行是一个 div一个单元格是一个 td 或者 div。这种方案在数据量小的时候没问题但一旦行数上千、列数上百DOM 节点数量就会爆炸滚动和重绘的性能会急剧下降。你可能会说可以用虚拟滚动只渲染可视区域这确实能缓解但虚拟滚动本身也有复杂度而且单元格内的富文本、公式高亮、选区绘制这些需求用 DOM 做起来依然很别扭。Univer 选择 Canvas 作为渲染底座逻辑很直接Canvas 是一块画布所有单元格、文字、边框、选区都是画上去的浏览器只需要维护一个 Canvas 元素DOM 节点数量恒定。这样一来无论表格有多少行多少列渲染压力都只和可视区域有关和总数据量无关。这就像你在一张巨大的纸上画画纸有多大不重要你只需要画眼睛能看到的那一块。当然Canvas 也有代价。DOM 天然支持文本选择、无障碍访问、CSS 样式Canvas 里这些都要自己实现。Univer 的做法是在 Canvas 之上抽象出一套自己的渲染层和事件系统把选区、光标、输入框这些交互都模拟出来。比如你在单元格里双击进入编辑态时它其实是在 Canvas 上方浮了一个真正的输入框编辑完成后再把内容画回 Canvas。这种“Canvas 为主、DOM 为辅”的混合模式是目前高性能表格引擎比较常见的做法。2.2 插件架构解决了什么问题Univer 的另一个核心设计是插件化。你可以把它想象成一台电脑主机核心运行时是主板和电源各种功能比如公式计算、条件格式、协同编辑、导入导出都是插在主板上的板卡。你需要什么就插什么不需要的就不插这样打包出来的体积和运行时开销都可控。这种设计的好处在实际项目中非常明显。比如你只是做一个简单的数据展示表格那只需要核心渲染插件加一个基础数据插件就够了公式引擎、协同模块都可以不引入。而如果你要做在线 Excel那就把公式、筛选、排序、图表这些插件都加上。插件之间通过事件总线和共享状态通信彼此解耦你甚至可以自己写插件来扩展功能。我踩过的一个坑是早期版本里插件的注册顺序会影响功能是否生效。比如公式插件必须在数据插件之后注册否则公式计算时拿不到单元格数据。这个顺序在文档里不一定写得很显眼但实际跑起来如果公式不生效第一件事就是检查插件注册顺序。2.3 与 Node.js 的关系为什么热词里会出现 Node.js很多人看到 Univer 相关搜索里带着 Node.js会疑惑一个前端表格引擎和 Node.js 有什么关系。其实关系主要在工程化和服务端渲染两个层面。一方面Univer 的源码是用 TypeScript 写的构建、打包、本地开发服务器都依赖 Node.js 环境你需要用 npm 或 pnpm 来安装依赖、跑开发脚本。另一方面如果你要做协同编辑服务端通常也是 Node.js 写的用来处理 WebSocket 连接和操作变换。所以如果你还没装 Node.js那第一步就是把它装好。我建议用 LTS 版本比如 18.x 或 20.x太新的版本有时候某些构建工具还没跟上容易出奇怪的错。安装步骤很简单去官网下载对应系统的安装包一路下一步就行。装完之后在终端里跑node -v和npm -v能打印出版本号就说明成功了。如果你在 CentOS 这类 Linux 服务器上部署可以用 nvm 来管理 Node.js 版本比直接装系统包灵活很多。3. 核心细节解析与实操要点从零跑起一个 Univer 表格3.1 环境准备与依赖安装在开始之前确认你的机器上已经装好了 Node.js 和包管理器。我个人习惯用 pnpm因为它在处理 monorepo 依赖时更快也更省空间但 npm 和 yarn 也完全没问题。下面以 npm 为例。首先创建一个空目录初始化一个前端项目。如果你用 Vite可以直接用模板创建npm create vitelatest my-univer-demo -- --template vanilla-ts cd my-univer-demo npm install然后安装 Univer 的核心包。Univer 把功能拆成了很多包最基础的是核心运行时和几个预设包。我一般会先装这几个npm install univerjs/core univerjs/design univerjs/engine-formula univerjs/engine-render univerjs/sheets univerjs/sheets-ui univerjs/ui这里解释一下每个包的作用。univerjs/core是核心提供依赖注入、事件总线、生命周期这些基础设施。univerjs/engine-render是渲染引擎负责 Canvas 绘制。univerjs/engine-formula是公式引擎。univerjs/sheets是表格数据模型univerjs/sheets-ui是表格的交互界面univerjs/ui是通用 UI 组件。univerjs/design是设计系统提供主题和基础样式。装完之后你还需要引入样式文件。Univer 的样式是分开的需要在入口文件里手动 import否则界面会错乱。这一点很容易被忽略我第一次跑的时候就是忘了引样式结果表格画出来了但工具栏全是裸的。3.2 最小可运行示例的代码结构下面是一个最小可运行的 Univer 表格示例。我把它拆成几步方便你对照理解。第一步在 HTML 里准备一个容器div idapp styleheight: 100vh; width: 100vw;/div第二步在 TypeScript 入口文件里初始化 Univerimport { Univer, LocaleType, merge } from univerjs/core; import { defaultTheme } from univerjs/design; import { UniverFormulaEnginePlugin } from univerjs/engine-formula; import { UniverRenderEnginePlugin } from univerjs/engine-render; import { UniverUIPlugin } from univerjs/ui; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverSheetsUIPlugin } from univerjs/sheets-ui; import univerjs/design/lib/index.css; import univerjs/ui/lib/index.css; import univerjs/sheets-ui/lib/index.css; const univer new Univer({ theme: defaultTheme, locale: LocaleType.ZH_CN, }); univer.registerPlugin(UniverRenderEnginePlugin); univer.registerPlugin(UniverFormulaEnginePlugin); univer.registerPlugin(UniverUIPlugin, { container: app, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsUIPlugin); univer.createUnit(UniverSheetsPlugin, { id: demo-sheet, name: 示例表格, sheetOrder: [sheet-01], sheets: { sheet-01: { id: sheet-01, name: Sheet1, rowCount: 100, columnCount: 20, cellData: { 0: { 0: { v: 姓名 }, 1: { v: 年龄 }, 2: { v: 城市 }, }, 1: { 0: { v: 张三 }, 1: { v: 28 }, 2: { v: 北京 }, }, 2: { 0: { v: 李四 }, 1: { v: 32 }, 2: { v: 上海 }, }, }, }, }, });这段代码跑起来之后浏览器里就会出现一个带工具栏的表格里面有三列数据。你可以点击单元格、输入内容、拖动选区基本交互都有了。3.3 插件注册顺序与依赖关系上面代码里插件注册的顺序不是随便写的。UniverRenderEnginePlugin必须在UniverSheetsUIPlugin之前因为后者依赖前者提供的渲染能力。UniverFormulaEnginePlugin要在UniverSheetsPlugin之前因为表格数据模型初始化时会去拿公式引擎的实例。如果你顺序写反了控制台会报依赖找不到的错误。我整理了一个常见插件的依赖顺序表供你参考插件作用建议注册顺序UniverRenderEnginePluginCanvas 渲染引擎1UniverFormulaEnginePlugin公式计算引擎2UniverUIPlugin通用 UI 与主题3UniverSheetsPlugin表格数据模型4UniverSheetsUIPlugin表格交互界面5UniverSheetsFormulaPlugin表格公式联动6这个顺序不是绝对的但按这个来基本不会出错。如果你要加协同插件协同插件一般放在最后注册因为它需要监听前面所有插件产生的操作。3.4 数据模型与单元格配置Univer 的表格数据模型是cellData结构是行索引 - 列索引 - 单元格对象。单元格对象里v是值f是公式s是样式。比如你要设置一个公式可以这样写cellData: { 0: { 0: { v: 总分 }, 1: { f: SUM(B2:B10) }, }, }样式s可以引用一个样式表里的 ID也可以直接内联。我一般会把样式统一注册到styles里然后在单元格里引用这样复用性好也方便后面改主题。注意rowCount和columnCount决定了表格的初始行列数但 Univer 支持动态扩展。如果你不确定数据量可以先把行列数设大一点比如 1000 行 50 列实际渲染时只会画可视区域不会因为设大了就卡。4. 实操过程与核心环节实现把表格接入真实业务4.1 从静态数据到动态加载上面的示例是写死的数据。真实项目里数据通常来自接口。你需要做的是先创建一个空的 Univer 实例等接口返回数据后再通过 API 把数据写进去。Univer 提供了getActiveSheet()和setCellValue()这类方法但更高效的方式是直接操作数据模型。我一般会封装一个loadData函数接收二维数组然后批量写入。批量写入比逐个单元格设置快很多因为 Univer 内部会做批量更新和重绘合并。如果你逐个设置每设一个就触发一次重绘数据量大了会明显卡顿。function loadData(univer, sheetId, rows) { const workbook univer.getUniverSheet(); const sheet workbook.getSheetBySheetId(sheetId); const cellData {}; rows.forEach((row, rowIndex) { cellData[rowIndex] {}; row.forEach((value, colIndex) { cellData[rowIndex][colIndex] { v: value }; }); }); sheet.setCellData(cellData); }这个函数跑完之后表格会自动刷新。实测下来一千行二十列的数据批量写入基本在一百毫秒以内完成用户几乎无感。4.2 公式计算与依赖追踪Univer 的公式引擎支持大部分常用函数比如 SUM、AVERAGE、IF、VLOOKUP 这些。公式的计算是惰性的只有单元格被渲染时才会去算而且会缓存结果。如果你改了某个单元格的值依赖它的公式会自动重新计算这个依赖追踪是引擎内部维护的。我遇到过一个情况从接口拿到的数据里公式是以字符串形式存在的比如A1B1。直接塞进v里是不行的必须放到f字段。而且公式里的单元格引用要用 Univer 自己的格式行列索引从 0 开始但公式里写的是 A1、B2 这种。Univer 会自动解析你不需要手动转换。实操心得如果你发现公式不计算先检查三件事。一是公式引擎插件有没有注册二是公式字符串是不是以等号开头三是引用的单元格是不是在rowCount和columnCount范围内。超出范围的话公式会返回错误值。4.3 选区、编辑与事件监听Univer 的交互事件是通过事件总线分发的。你可以监听选区变化、单元格编辑、滚动等事件来做一些业务逻辑。比如用户选中某个区域后你想在侧边栏显示这个区域的统计信息就可以监听选区变化事件。import { SelectionManagerService } from univerjs/sheets-ui; const selectionManager univer.getInjector().get(SelectionManagerService); selectionManager.selectionChanged$.subscribe((selections) { console.log(当前选区, selections); });编辑事件也类似你可以监听cellEditStart和cellEditEnd在编辑前后做校验或者记录日志。我做过一个需求是某些单元格只允许输入数字如果用户输入了非数字就弹提示并回滚。这个就是在编辑结束事件里做的校验。4.4 样式与主题定制Univer 的主题系统基于 CSS 变量和设计令牌。你可以通过覆盖defaultTheme里的颜色值来改整体配色也可以针对单个单元格设置样式。单元格样式支持字体、字号、颜色、背景、边框、对齐方式这些常用属性。const myTheme merge({}, defaultTheme, { primary: { 500: #1677ff, }, });如果你要做深色模式可以准备两套主题在运行时切换。Univer 的 UI 组件会跟着主题走不需要你一个个去改样式。这一点比我之前用过的很多表格组件都省心。5. 常见问题与排查技巧实录5.1 表格不显示或白屏这是最常见的问题原因通常有几个。第一容器元素没有设置高度。Univer 的 Canvas 需要容器有明确的宽高如果你只写了width: 100%但父元素没有高度Canvas 高度就是 0自然什么都看不到。第二样式文件没引入。Univer 的 UI 依赖 CSS不引样式的话工具栏和表格容器可能被隐藏或者错位。第三插件注册顺序不对导致初始化中断。排查顺序建议是先看控制台有没有报错再看容器尺寸最后检查插件注册。我一般会在初始化之后打印一下univer.getUniverSheet()如果返回 undefined说明表格单元没创建成功。5.2 公式不生效或显示为文本公式不生效九成是因为公式字符串放错了字段。记住v是值f是公式。如果你把SUM(A1:A5)放到v里它就会被当成普通文本显示。另外公式引擎插件必须在表格插件之前注册否则表格初始化时拿不到公式引擎公式就不会被解析。还有一种情况是公式引用了不存在的单元格。比如你写了Z100但表格只有 20 列 100 行Z 列和 100 行都超出了范围公式就会返回#REF!错误。这时候要么扩大行列数要么修正公式引用。5.3 大数据量下的性能问题虽然 Canvas 渲染本身很快但如果你一次性写入几万行数据初始化还是会卡。我的做法是分页加载或者只加载可视区域附近的数据。Univer 支持动态插入行你可以监听滚动事件快滚到底部时再加载下一批。另外避免在循环里逐个设置单元格样式。样式设置比值设置更耗性能因为每次都要重新计算渲染属性。如果一批单元格样式相同可以先用setStyle批量设置或者直接注册一个命名样式然后让单元格引用这个样式 ID。5.4 协同编辑时的冲突处理如果你要做多人协同Univer 提供了协同插件但服务端需要自己实现。核心思路是每个操作都带上版本号和用户 ID服务端按顺序广播客户端收到后应用操作。冲突处理一般用 OT 或者 CRDT 算法Univer 的协同插件对这两种都有支持但配置起来比较复杂。我建议如果只是小规模协同比如几个人同时填一个表可以用简单的锁机制谁先选中单元格谁就锁定其他人只能看不能改。这样实现简单也不会出现复杂的冲突。等业务量大了再上完整的 OT 方案。5.5 常见问题速查表问题现象可能原因解决方法白屏无报错容器高度为 0给容器设置明确高度界面错乱样式未引入引入 design、ui、sheets-ui 的 CSS公式显示为文本公式放到了 v 字段改为放到 f 字段公式返回 #REF!引用超出行列范围扩大 rowCount/columnCount插件报依赖错误注册顺序不对按渲染、公式、UI、表格顺序注册大数据量卡顿逐个设置单元格批量写入分页加载编辑事件不触发事件服务未获取通过 injector 获取对应 Service6. 扩展方向与个人经验补充Univer 的插件架构意味着它的扩展性很强。你可以自己写插件来加功能比如自定义工具栏按钮、自定义右键菜单、自定义公式函数。我写过一个小插件用来在表格里高亮重复值实现方式就是监听数据变化然后遍历单元格给重复的值设置背景色。整个过程不需要改 Univer 源码只需要注册一个插件在合适的生命周期里挂上逻辑。另一个扩展方向是导入导出。Univer 有对应的导入导出插件支持 Excel 文件的读写。如果你要做数据导入可以用这个插件把 Excel 解析成 Univer 的数据模型然后渲染出来。导出也类似把当前表格数据序列化成 Excel 文件下载。不过导入导出对复杂格式的支持有限比如图表、宏这些可能丢失用之前最好先测试一下你的目标文件格式。我个人在实际操作中的体会是Univer 的学习曲线主要在前期的概念理解上一旦你搞清楚了插件注册、数据模型、事件总线这三件事后面就是查 API 拼功能。它的文档虽然不算特别详细但示例代码比较全遇到问题先去翻示例大部分都能找到答案。另外社区里有一些人分享的实战经验质量参差不齐建议以官方示例为准不要盲目抄网上的配置。最后再分享一个小技巧如果你在本地开发时遇到奇怪的渲染问题可以先清空浏览器缓存或者用无痕模式打开。Univer 的 Canvas 渲染有时候会被浏览器缓存影响尤其是你改了主题或者样式之后旧缓存可能导致显示不一致。这个坑我踩过好几次后来养成习惯改完样式先硬刷新。
