Univer集成实践：Web类Excel应用从选型到二开落地

如果你最近在技术群里搜“univer在线报表怎么集成”，多半会看到有人提到 Univer 这个开源项目。我第一次听到这个名字的时候也愣了一下，以为是什么新框架的缩写，后来发现它就是一个想把 Office 套件搬到浏览器里的开源项目。我因为要给内部供应链看板做“可编辑物料主数据维护表”，花了两周时间把老的 HTML table 换成 Univer，中间踩了不少文档里没写明白的坑。这篇文章把我实际接入和二次开发的完整过程整理出来，包括技术选型对比、Canvas 渲染原理、依赖安装、数据映射、保存回写、权限校验、协同方案取舍，以及我会后总结的避坑清单。适合正在评估“在 Web 端做类 Excel 应用”的开发者、前端负责人和产品同学，无论你是打算自己集成，还是先搞清楚这个开源方案的边界，这篇都值得花十分钟看完。

1. 先搞清楚 Univer 是干嘛的，再决定要不要接入

1.1 Univer 在办公套件里的位置：它不是单纯的网页 Excel

Univer 一开始给人印象最深的是在线电子表格，但现在的定位已经不只是表格了，它是一套可以在浏览器里运行的办公套件基础框架，目前覆盖 Sheet、Doc、Slide，其中被用得最多、生态最完整的还是 Sheet。也就是说，你可以把它理解成“前端版本的 Excel 核心能力”，但它又不只是把 Excel 的界面抄一遍，而是把单元格编辑、行列操作、公式计算、样式渲染这些能力做成了可编程的组件，方便业务系统直接嵌入。

在真实项目里，它的核心价值体现在一个词：可交互。以前我们做数据展示，最常见的方式是后端生成 Excel 让用户下载，或者前端用表格组件做一个只读列表。但一旦业务希望用户在网页里直接填报、修改、跨表格引用数据，普通表格组件就不行了。Univer 这类方案把“网页里的 Excel 体验”变成了工程上可控的事情，而不是从零开始做合并单元格、拖动填充、公式引擎这些地狱级功能。

1.2 为什么说大部分做嵌入表格的人没必要完全自研

我见过不少团队最开始的想法是“我们需求没那么复杂，自己用 HTML table 拼一个就够了”。这个思路在小范围、纯展示、列数固定的场景下确实能跑，但一旦业务方说出“我要像 Excel 一样拖动填充”“我要跨 sheet 引用单元格”“我要撤销重做”，项目性质就变了。

我举一个实际例子。有一段时间我们内部工作台里要维护几百个供应商的资质信息，最初就是用原生 table 渲染，编辑靠弹窗。后来销售运营提了一个需求：希望像 Excel 一样批量修改整列、批量复制粘贴、输入公式自动计算得分。原生 table 方案直接崩了，因为粘贴解析、行列坐标映射、样式合并、公式联动都不是加两个函数能解决的问题。Univer 这类成熟方案相当于把这些基础能力封装成了底层引擎，我们要做的是在这上面接业务逻辑，而不是重复造轮子。

当然也不是说所有人都有必要用这么重的东西。如果业务只是展示数据、不需要用户编辑，那用普通表格组件可能更轻。但如果你明确预见到会有类 Excel 的交互需求，我建议从第一天就引入 Univer，不要等业务要求来了再重构。

1.3 和常见方案的对比：选型时到底该看什么

很多人在评估的时候会拿 Univer 跟 Luckysheet、Handsontable、SpreadJS 放在一起对比。我的看法是，不要只看官网演示效果，要从“你的业务需要哪些能力”出发。

我的建议是，先把“是不是一定要像 Excel”这个问题想清楚。如果只是数据录入网格，Handsontable 可能更好，因为轻、容易上手。如果要类 Excel 体验又要开源可控，Univer 的优势明显，因为它从一开始就是按可扩展办公套件来设计的，而不是一个孤立的表格组件。

2. 打开引擎盖：Univer 的设计思路为什么适合二开

2.1 Canvas 渲染：用绘制换掉整棵 DOM 树，滚动才不卡

这里涉及 Univer 比较核心的技术选择：它没有用传统 DOM 表格来实现界面，而是用 Canvas 自绘渲染。简单说，页面里只有一个 Canvas 画布，单元格、边框、选区、滚动条全是代码“画”上去的。

为什么这样设计？我们可以用地图应用来类比。你打开在线地图拖动时，地图不可能把全世界所有道路都建在 DOM 节点里，而是只渲染你当前视野范围内的内容，超出视口的就丢弃。Univer 的表格渲染也是这个思路：一个表格可能有几万行、几十列，如果用 DOM 节点去渲染，哪怕浏览器能撑住，滚动时也会因为节点太多而卡顿；但 Canvas 只绘制当前可见区域，滚动时不断重绘，性能表现会稳定很多。

这个设计对二次开发的启发是：不要试图去操作表格里的 DOM 节点，Univer 的核心数据模型和渲染是分开的。你要改变单元格内容，就改数据，然后触发重绘，而不是手动去改某个 td 的 innerHTML。理解了这一点，后面做数据回写和自定义渲染时才不会走弯路。

2.2 插件化架构：核心保持稳定，业务功能全部外挂

对开发者来说，Univer 的插件化架构可能是最重要的设计决策。它的核心包只负责工作簿生命周期、命令系统、数据模型和协同基础，而工具栏、公式、筛选、排序、图表这些能力都通过插件注册进去。你可以只装 Sheet 插件，不用 Doc；也可以只装数据展示，不装 UI 插件，完全自己定制界面。

这个设计的直接好处是业务代码可以不侵入核心。比如我们在内部系统里要加一个“数据审核”按钮，只需要注册一个自定义插件，监听某个工具栏事件，然后在自己的模块里处理审核逻辑，不需要去改 Univer 源码，也不需要 fork 一份。

分层理解也很重要：最底层是 core，提供数据模型；中间是插件层，提供具体能力；最上面是 Facade 或对外 API，负责让业务代码方便地调用。一旦遇到版本升级，我们只需要检查自己调用的 API 是否变化，不需要理解 Univer 内部的每一个改动。

2.3 多端适配和框架无关：React、Vue、甚至原生页面都能接

Univer 的核心是 TypeScript 编写的，而且核心层做了框架无关设计。无论你的页面是 React、Vue，还是原生 JavaScript，都可以通过它的 UI 插件或自定义壳子接入。

我刚开始也有一个担忧：既然它有自己的 UI 插件，会不会被 React 项目绑死？实际上它把 UI 层做成了可替换的。官方提供了开箱即用的 UI 插件，但如果你想用自己的工具栏、自己的顶部按钮，完全可以在容器里只初始化表格画布，其他交互按钮用框架自己的方式实现。

对我们这种维护了好几个不同技术栈内部系统的团队来说，这个特性很关键。因为同一个 Univer 表格能力可以被 React 的管理后台、Vue 的可视化平台甚至一个纯 HTML 页面复用，只需要封装一层适配代码。这也是为什么很多选型评估中，我最后投了 Univer 而不是某个绑定框架的方案。

2.4 协同编辑：它在架构上被当成一等公民

在线表格如果要做到多人同时编辑，最麻烦的不是传输数据，而是冲突处理。两个用户同时修改同一个单元格，最终以谁为准？两个用户分别插入行列，合并后顺序怎么处理？这套逻辑非常复杂，如果一开始不设计，后面别说接入了，连改都很痛苦。

Univer 在架构上把协同设计成了底层能力，用户产生的每次修改都会变成一条命令，命令可以被记录、广播和合并。这种设计思路让多人编辑不是“保存时覆盖”，而是有无限接近在线文档的同步体验。不过要注意，Univer 给的是客户端这一侧的基础，真正的多人协同还需要有服务端配合，比如 WebSocket 通道、房间管理、断线重连，这些我在第 4 节详细说。

3. 实操：从五分钟 Demo 到能上线的表格页面

3.1 环境准备和依赖安装

先说环境。我实际用的项目是 Vite + Vue 3，Node 版本 18。Univer 是一个多包结构，不是安装一个包就完事，至少需要核心包、Sheet 插件、UI 插件，以及对应的业务 UI 插件。

npm install @univerjs/core @univerjs/sheets @univerjs/ui @univerjs/sheets-ui

这里特别提醒一下版本问题：Univer 从早期到 1.x 版本之间做过包名和 API 的重大调整，网上很多文章的代码可能已经过时。安装完依赖后，先到 package-lock.json 或 pnpm-lock.yaml 里确认所有 @univerjs 相关包版本一致。如果核心是 1.0.x，UI 插件却是 0.2.x，大概率启动报错。这个坑我踩过，而且报错信息往往不直接说是版本冲突，而是某个模块找不到。

需要公式支持的话，再加这两个：

npm install @univerjs/sheets-formula @univerjs/sheets-formula-ui

如果你是 Next.js 或 Nuxt 这类 SSR 框架，还要注意 Canvas 相关模块只能在浏览器端加载，不能直接放在服务端执行。

3.2 初始化一个最小可运行的表格实例

页面里先放一个挂载点：

<div id="app" style="width: 100vw; height: 100vh"></div>

然后初始化：

import { Univer, LocaleType } from '@univerjs/core'; import { defaultTheme } from '@univerjs/design'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverUIPlugin } from '@univerjs/ui'; import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'; const univer = new Univer({ locale: LocaleType.ZH_CN, theme: defaultTheme, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverUIPlugin, { container: 'app', }); univer.registerPlugin(UniverSheetsUIPlugin);

如果一切正常，页面上会出现一个空的工作簿，可以手动敲字，可以合并单元格，也可以右键插入行。这已经相当于拿到了一个浏览器里的 Excel 核心。

还是要啰嗦一句，不同版本之间 API 名字可能有差异，比如有的版本用createUniverSheet创建 sheet，有的版本换了方法名。遇到类似问题不要去猜，直接打开node_modules里对应的包然后搜索方法名，或者查官方文档的升级迁移说明，比自己试错快得多。

3.3 把后端数据映射成工作表

空表格没意义，接业务数据才是关键。假设后端返回了一个物料列表，前端需要把它转换成 Univer 的工作簿配置格式。最核心的结构是这样的：

const workbook = { id: 'workbook-0001', sheets: [ { id: 'sheet-0001', name: '库存明细', rowCount: 100, columnCount: 20, cellData: { A1: { v: '物料编码' }, B1: { v: '物料名称' }, C1: { v: '库存数量' }, A2: { v: 'MAT001' }, B2: { v: '螺丝 M3' }, C2: { v: 5000 }, }, }, ], }; univer.createUniverSheet(workbook);

A1这种 key 是列字母加行号，v是单元格的值。实际项目中，后端接口通常返回的是数组对象，我们需要自己做一层转换：把行数据遍历，根据列配置生成A1、B1这样的 key 再写入cellData。

这块的经验是：A1 坐标转换放在前端做，不要在后端拼。因为用户可能在网页里增删列，一旦列序变化，后端拼好的坐标就全错了。前端始终以“当前列配置”为准，动态生成坐标，这样才能保证数据对得上。

3.4 保存编辑结果：数据回写的正确姿势

表格能用以后，第一个要解决的问题是怎么把用户编辑的结果拿回来。最简单的方式是在用户点“保存”时，从当前激活的工作表里读取数据快照：

const workbook = univer.getActiveWorkbook(); const sheet = workbook.getActiveSheet(); const snapshot = sheet.getSheetData(); // snapshot 结构与 cellData 对应，可以 JSON 序列化后发给后端 api.saveSheet(workbook.id, sheet.id, snapshot);

但如果你真这么做了，上线前要做好准备面对两个问题：第一，全量保存。用户只改了一个单元格，你却把整个工作簿几万个单元格全部提交，后端接口压力很大，网络请求体积也巨大；第二，频繁触发。如果监听每次单元格变更事件就保存一次，用户连续录入十个数字就会发十个请求。

我的做法是两层控制：一是保存按钮手动提交，不自动保存；二是提交前做一个变更差异计算，只把新增或修改过的单元格传给后端。实现差异计算时，可以保留一份最初的快照，然后递归比较当前快照，把值不同的单元格筛选出来。这个逻辑不难，但对线上环境的长期稳定非常重要。

如果确实需要自动保存，一定要用防抖。可以理解为用户停止输入后再过 500 毫秒才触发保存，避免每次击键都请求。

3.5 二开示例：自定义公式与自定义单元格

Univer 支持注册自定义公式，这意味着业务人员可以直接在单元格里写公式来完成复杂计算，不用回后端跑接口。我举个例子，我们要计算“毛利率”，运营习惯直接输入=GROSS_MARGIN(C2,D2)，其中 C2 是销售额，D2 是成本：

import { UniverFormulaEnginePlugin } from '@univerjs/sheets-formula'; const formulaPlugin = univer.getPlugin(UniverFormulaEnginePlugin); formulaPlugin.registerFunction('GROSS_MARGIN', (revenue: number, cost: number) => { if (!revenue) { return null; } return (revenue - cost) / revenue; });

注册完以后，用户在单元格里输入=GROSS_MARGIN(C2,D2)，公式引擎会调用我们的函数并显示结果。这个功能非常实用，尤其是业务方不想依赖开发反复改逻辑的时候，公式可以在表格里自行组合。

再比如自定义单元格渲染。默认单元格只能显示文本或数字，但业务里我们想让“供应商状态”这一列直接显示红色“异常”或绿色“正常”。Univer 支持自定义单元格渲染器，本质上是你在渲染阶段拿到单元格数据，然后绘制自己的内容，可以画背景色、加角标、显示图标。这个能力跟 Canvas 渲染是一体的，不需要走 DOM，所以性能也不差。

4. 企业内落地：比 Demo 复杂得多的三件事

4.1 性能与体积：按需加载、虚拟化边界和公式限制

Univer 的功能很多，能力也随之而来的是体积不轻。如果直接把所有插件打进主包，首屏加载会有明显压力，尤其是内部系统通常在低带宽环境访问。

解决办法是动态导入和按需注册。比如只做表格业务时，不应该引入 Doc 和 Slide 相关包；公式插件如果暂时不用，也不要注册。代码层面可以这样处理：

const { Univer } = await import('@univerjs/core'); const { UniverSheetsPlugin } = await import('@univerjs/sheets'); const { UniverUIPlugin } = await import('@univerjs/ui'); const { UniverSheetsUIPlugin } = await import('@univerjs/sheets-ui');

另外要控制单个工作表的数据规模。Univer 的 Canvas 渲染虽然能应对大数据量，但公式计算和筛选排序这类逻辑仍然有性能瓶颈。我的经验是，一个 sheet 里行数超过两三万行而且带公式时，公式重算会明显变慢。如果业务有这么大的数据量，优先考虑拆分 sheet，或者把汇总逻辑放到后端，前端只展示结果。

还要考虑浏览器标签页恢复。用户可能开了很多内部系统页面，内存占用大了以后表格会出现白屏。我们后来加了定时保存，并且提示用户不要把多个大表格同时打开。

4.2 权限与安全：前端拦截只是表面，服务端校验才是底线

在线表格接入业务系统后，最容易被忽略的就是权限。很多人觉得“我能控制按钮显隐，不该让用户点的按钮藏起来就够了”，实际上远远不够。用户完全可以绕过前端 UI，直接调用 Univer 的 API 修改数据，或者抓包模拟保存请求。

Univer 提供了命令机制，我们可以在命令执行前做权限校验。比如检测到当前用户没有“修改”权限时，就阻断编辑类的命令，界面上表现为不可编辑。这是一个很好的体验层防线。但真正保证数据安全的，是后端的权限校验：每次保存请求都需要带上用户凭证，后端检查用户对这个 sheet 有没有写权限，检查提交的数据版本号是不是最新的，防止旧数据覆盖新数据。

这里分享一个我们内部踩过的坑：最开始只在前端通过按钮显隐控制权限，结果测试同事从控制台直接调 API 把一条物料的价格改成了负数，数据直接入库。后来我们改成“前端做拦截提示 + 后端做写入校验”的双层机制，才彻底堵住这种绕行风险。前端是用户体验，后端才是数据安全。

4.3 协同方案：不是引入依赖就算支持多人编辑

很多团队看到 Univer 支持协同，以为部署完就能像腾讯文档一样多人同表编辑。这里必须说清楚：Univer 在客户端解决了协同的数据结构和命令同步基础，但生产环境依然要自己搭建服务端。

完整的多人编辑需要几个组件：WebSocket 长连接用来广播命令，房间服务用来管理“哪些用户在看同一张表”，服务端文档状态用来处理操作合并和冲突，还需要断线重连和补拉增量逻辑。这些工作量并不小，如果内部没有现成的实时通信基础设施，我劝大家第一步别直接上真协同。

我推荐一个折中方案：先做“抢占式编辑”。意思是同一时间只允许一个人编辑某个 sheet，其他人都是只读模式。点击编辑时，后端锁定这个 sheet，用户退出编辑时释放锁。实现上只需要在保存接口做一次锁定校验，成本非常低，但已经能覆盖绝大多数内部数据维护场景。等业务确实需要多人同时在线编辑了，再去考虑完整的协同服务端建设。

4.4 版本管理：锁定版本，别追新

Univer 迭代速度很快，新的特性和插件不断出现，但我对生产项目的强烈建议是：不要追新，锁定版本。

原因很简单：它的 API 还在快速演进，小版本之间都可能出现方法重命名、参数变化。我们生产环境目前锁定的是一组固定的版本号，除非要升级新功能，否则不会随意更新。升级前一定要做三件事：第一，备份当前配置，记录所有自定义插件和改动点；第二，查看官方 Changelog，确认是否有破坏性变更；第三，升级后跑一遍核心流程回归，包括公式计算、保存回写、权限拦截。

还有一个细节：锁定版本要用精确版本号，不要用^1.0.0这种范围版本，否则 npm 在重新安装依赖时会自动拉到最新的 1.x，导致测试环境和生产环境行为不一致。我在项目中直接在 package.json 里写死版本号，并提交 lockfile，确保所有开发机一致。

5. 常见问题与排查思路速查

接入过程中我整理了一个排查表，基本能覆盖团队里新人问我的大多数问题。

这个列表不是万能的，但覆盖了绝大多数“从 Demo 到上线”阶段会遇到的问题。特别是版本不一致和数据覆盖这两个，我几乎每次帮同事排查都能遇到。

最后分享一个我自己的体会。Univer 这类开源项目，最怕的不是上手难，而是团队把它当成“下一个 Excel”然后把所有需求都往里面塞，最后被复杂度和版本变化拖垮。明确它的边界——它是一个非常优秀的表格渲染引擎和一个可扩展的办公套件底座，而不是完整的业务后端——反而能让集成工作做得更稳妥。我现在的做法是：任何新增需求都先问一句，这个能力在 Univer 里是配置项、插件还是需要自己写服务端逻辑，分清楚之后再去排期，整个落地过程会顺畅很多。