Univer深入解析：从在线表格选型到协同编辑落地的完整实践

做 Web 应用这几年，我遇到过不少返工率极高的需求，"在浏览器里做表格"绝对排前三。客户描述得很简单：页面里放一张表，能填数据，能算公式，最好和 Excel 长得差不多。可一旦动手，公式引擎、剪贴板、撤销重做、超大表格渲染、协同编辑，每一项都是无底洞。我最早用的是 Luckysheet，后来因为协同和长期维护的问题换成自研方案，折腾了两个月只做出来一个"能看不能算"的空壳。接触到 Univer 之后，我才真正把在线表格这件事跑通。它是一套在浏览器里运行的办公套件内核，电子表格、文档、幻灯片共用同一套数据模型和渲染引擎，完全开源，代码在 GitHub 上公开可查。同时官方也提供了"univer在线"的托管版本，所以现在搜这个词的人特别多。这篇文章把我从调研、选型到真实项目接入的全过程写出来，重点讲清楚架构模块、接入步骤、协同思路，以及那些文档里查不到但要实测才会遇到的坑。

1. 我为什么在对比了一圈表格引擎之后选了 Univer

先说结论：如果你只是要在页面上展示一张静态报表，任何表格库都能干，挑顺眼的就行。但凡是涉及"用户像用 Excel 一样去编辑、计算、协作"的场景，可选范围立刻缩到很小，而且每个方案都有让你难受的地方。

1.1 传统方案各有各的难处：几个绕不开的老对手

我这次选型前后对比了五个方案，挨个试过 demo，也读了不少源码和 issue，感受如下。

Luckysheet是很多人第一个想到的开源方案，文档号称支持 Excel 的大部分功能，社区里也积累了相当多的二次开发案例。但它的问题同样明显：背后不是一个活跃的团队在持续投入，issue 堆积量很大，部分核心功能停留在"能跑"而不是"好用"；协同编辑能力一直没有形成稳定可用的开源方案。另一个坑是它的代码风格比较传统，想要深度定制，你得先适应它的内部约定。

Handsontable在表格交互上做得非常精致，渲染性能也不错，适合做数据录入类的界面。但它本质是"表格控件"，公式引擎、数据透视表这些办公能力默认不内置，哪怕要集成第三方公式库，也要自己处理很多边界问题。更重要的是它的商业授权模式：非开源协议，公司商用要买授权，这在大厂审批流程里很麻烦。

SpreadJS功能确实强，Excel 兼容性在国产商业产品里数一数二，文档也完善。缺点是贵，授权模式对一个还没验证商业模式的内部项目来说太重了。而且它是个封闭产品，你只能用它给的能力，没法动内核。

x-spreadsheet轻量是轻量，但功能天花板太低，做一些简单的 demo 可以，真要投入生产级表格，公式、格式、数据校验都不够用，基本不推荐认真考虑。

1.2 Univer 给出的答案：年轻、开源、完整

Univer 打动我的核心有几点。

第一，协议干净。开源版本用的是 Apache 2.0 协议，商用、二次开发、闭源部署都没有法律上的障碍，对中小企业尤其友好。这意味着我可以放心把它嵌进客户项目里，不用每次法务评审都提心吊胆。

第二，架构起点高。它不是从一个"单元格表格控件"慢慢往上长出来的，而是一开始就按"多文档类型统一内核"来设计的。同一个核心同时支撑电子表格、文档和幻灯片，这种设计思路在开源社区里几乎没有同类。带来的实际好处是：如果以后业务要加文档编辑模块，不需要再引入另一套完全不同技术栈的产品。

第三，社区活跃度让我敢押注。项目的更新节奏很快，几乎每个月都有版本迭代，issue 响应也积极。对于一个要从 0.x 版本开始投入使用的项目，这是最重要的安全感来源。GitHub 上 star 涨得飞快，说明踩坑的人多、反馈的人多、修复的速度也跟得上。

第四，在线版已经落地。如今搜"univer在线"能搜到大量讨论，本质上是官方推出了可直接使用的云端版本，适合不想自己维护基础设施的团队。开源版本和在线版本的关系类似很多开源软件与官方云服务的关系：你既可以自建，也可以买托管。

2. Univer 的模块拆解：入手前先认识这几个"零件"

很多人在接入 Univer 时会懵，因为它不是一个单一 npm 包，而是一堆包组成的框架。我第一次看文档时也被目录结构吓到，但理解了模块分工之后，这个设计反而会让后续开发省心不少。

2.1 核心包与插件包各自管什么

简单列一下我实际用到的几个包，以及它们在我心里的定位。

刚开始用的时候，只需要关心 @univerjs/presets 就够了。它会帮你把常用的内核、渲染、UI、公式等插件一次性组合好。只有当你开始二次开发、自定义插件、调性能时，才需要深入到 @univerjs/core 和各个 engine 包。

2.2 为什么偏偏用 Canvas 来渲染表格

Univer 的渲染引擎没有选择"一堆 div 拼单元格"的方案，而是在 Canvas 上直接绘制。这一点很多人想不通，觉得 Canvas 里做事件处理很麻烦。真实原因很简单：DOM 节点数量是撑不住表格规模的。

假设表格显示 30 行 x 15 列，450 个 DOM 节点浏览器还能忍。但用户滚动的时候，前端为了流畅，得动态回收和创建节点，逻辑复杂度立刻上来了。更别说选中区域的高亮、拖拽填充、公式引用框这些在 DOM 里都很难做到像素级精准。Canvas 方案没有这个瓶颈，它只需要维护一份"画什么"的指令列表，由渲染引擎根据视口位置只绘制可见区域，滚动时重绘整个画布的成本远低于操作一堆 DOM。

代价也很明显：你没法再通过 DOM 事件去监听单元格，一切交互都要自己算坐标、自己做命中测试。Univer 把这一层封装好了，对使用方来说无感，但理解这一点对排查渲染问题很有帮助——很多"表格不显示"的 bug，其实不是数据没加载，而是画布尺寸、视口计算出错。

3. 接入一个 Vue 3 + TypeScript 项目：从空目录到可编辑表格

理论说再多，不如直接把项目跑起来。下面这套流程是我在真实项目里验证过的，以 Vue 3 + TypeScript 为例，React 项目思路完全一致。

3.1 初始化项目并安装依赖

npm create vite@latest univer-demo -- --template vue-ts cd univer-demo npm install npm install @univerjs/presets

核心依赖其实只有 @univerjs/presets。如果你的项目对包体积很敏感，也可以不装 preset，改成按需安装 @univerjs/core、@univerjs/sheets、@univerjs/sheets-ui 等子包，但初期没必要折腾这个，先把功能跑通更重要。

3.2 用 createUniverSheet 完成最小接入

在 src/main.ts 里写这样一段：

import { createApp } from 'vue'; import App from './App.vue'; import { createUniverSheet } from '@univerjs/presets/lib/preset'; createApp(App).mount('#app'); const { univerAPI } = createUniverSheet({ container: 'app', locale: 'zhCN', });

对应模板里需要一个带 id 的容器，注意一定要给高度：

<template> <div id="app" style="width: 100%; height: 600px"></div> </template>

只要这一小段代码，页面上就会出现一个完整的、带工具栏和公式栏的电子表格。我当时看到这个效果确实是有点惊讶的——没有写任何样式，也不需要配置任何东西，Excel 的底子在浏览器里就这么出来了。

这里有个很容易踩的坑：容器没有设置高度时，Canvas 渲染引擎计算出来的画布尺寸是 0，表格区域会空白一片。排查的时候先别怀疑代码，先看容器尺寸。我记得有一次线上问题折腾了半小时，最后发现是父组件把高度折叠成了 0。

3.3 通过 univerAPI 读写单元格

接入表格只是第一步，业务系统真正关心的是怎么往里放数据、取数据。Univer 提供了一套面向开发者的 API，入口是创建实例时返回的 univerAPI。

const workbook = univerAPI.getActiveWorkbook(); if (!workbook) return; const sheet = workbook.getActiveSheet(); if (!sheet) return; // 写一片数据到 A1:J50 const range = sheet.getRange(0, 0, 50, 10); range.setValues( Array.from({ length: 50 }, (_, row) => Array.from({ length: 10 }, (_, col) => `R${row + 1}C${col + 1}`) ) ); // 读取 B2 的值 const value = sheet.getRange(1, 1).getValue(); console.log(value); // 读取整张表的数据快照 const snapshot = sheet.getSnapshot(); console.log(snapshot);

这里要注意两个细节。

一是getRange 的参数顺序是 (row, column, rowCount, columnCount)，不是 Excel 里常用的 A1 样式地址。传错参数不会报错，但你会往完全错误的位置写入数据。之前我把行列顺序搞反，表格里一半数据写到表格外面去了，查了半天才发现是这里错了。

二是写入操作尽量整块进行。上面用 setValues 一次写入 500 个单元格，比循环 500 次 setValue 性能好一个数量级。Univer 会把 setValues 当成一条命令整体处理，可以走统一的撤销栈；而 500 次 setValue 会产生 500 条命令，撤销时会把操作拆成 500 步，体验非常差。

3.4 给工作表加上公式、数据验证和条件格式

如果只想展示一张静态表，到上面那步就够了。但客户要的是"和 Excel 差不多"，所以公式、数据校验、条件格式这些必须安排上。

Univer 默认就集成了公式引擎，你只需要往单元格里写公式字符串：

sheet.getRange(3, 3).setFormula('=SUM(A1:A50)');

写完这个，D4 单元格会自动计算 A1 到 A50 的总和。如果我后面再往 A1:A50 写入数据，公式结果会跟着更新，这个联动是公式引擎负责维护的，不需要你手动触发。

数据验证也走 API。比如限制 B 列只能输入 1 到 100 的整数：

import { ValidationType } from '@univerjs/sheets'; sheet.getRange(0, 1, 100, 1).setValidator({ type: ValidationType.INTEGER, operator: 'BETWEEN', formula1: 1, formula2: 100, allowBlank: true, showErrorMessage: true, errorMessage: '请输入 1 到 100 之间的整数', });

条件格式我在早期版本里用起来略费劲，配置结构比较嵌套，但功能本身是完整的：

sheet.getRange(0, 0, 50, 10).setConditionalRules([ { type: 'cellIs', operator: 'GREATER_THAN', formula: ['80'], style: { fill: { patternType: 'solid', fgColor: 'fff2cd', }, font: { bold: true }, }, }, ]);

这段代码的效果是：A1:J50 里数值大于 80 的单元格，背景色变成浅黄，字体加粗。业务上做绩效看板、价格预警都很好用。

3.5 监听编辑事件并回写业务系统

表格在前端编辑完，数据最终要落到后端。Univer 提供了事件监听机制，我一般这么用：

let saveTimer: number | undefined; univerAPI.onCellChange((cellInfo) => { console.log('单元格发生变化', cellInfo); // 防抖 1 秒，避免用户连续输入时疯狂请求后端 clearTimeout(saveTimer); saveTimer = window.setTimeout(() => { const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook?.getActiveSheet(); if (sheet) { // 把整张表的数据序列化后传给后端 const payload = sheet.getSnapshot(); api.saveSheet(payload); } }, 1000); });

这种"全量快照 + 防抖保存"是省事做法，适合单用户编辑场景。多用户协同时这套逻辑不够，后面单独讲。

4. 协同编辑的核心逻辑：Univer 的"命令-操作"流

协同编辑是表格场景里最复杂的一块，也是很多团队选型时最纠结的。市面上开源表格库大多是单机版，协同要么闭源收费，要么不成熟。Univer 把协同相关的底层能力内建到了内核里，这也是我最终选它的重要原因。理解它之前，要先理解它的命令系统。

4.1 为什么说 Univer 里的每次编辑都是一条命令

在 Univer 里，用户做的每件事——输入值、改样式、删行加列——都会被封装成一条结构化命令，命令执行后产生对应的操作记录。你手动调 setValues、setFormula 时，同样走这条命令通道。

这个设计的价值在于：所有变更都变成了可描述、可传输、可回放的数据。单人场景下，命令进入撤销/重做栈；多人场景下，命令在用户之间同步，每个人都按相同顺序执行相同的命令，最终状态自然一致。这是 OT 协同模型相对容易落地的原因，因为它天然具备"所有操作都能序列化"的前提。

从实践角度说，这也是纯前端方案和协同方案的真正分水岭。很多表格库之所以很难做协同，就是因为编辑动作分散在各个地方，有的走事件、有的直接改数据，根本没有统一的"操作流"概念。

4.2 多人协同至少需要补上哪几块拼图

Univer 内核提供的是命令和操作的基础设施，但要真正上线一套协同编辑，还需要自己去补齐以下模块。

第一是传输通道。最简单的方式是 WebSocket：用户 A 的每条命令发给服务端，服务端广播给房间内其他用户，其他人拿到命令后在本地的 Univer 实例里执行。消息结构可以很简单，就是把命令的序列化结果原样转发。

第二是时序一致性。如果两个用户几乎同时改同一个单元格，服务端必须定义好处理顺序。我用过两种策略：一种是服务端串行化处理，谁先到谁先执行，后到的命令基于最新状态执行；另一种是引入版本号机制，用户执行命令前带上自己看到的版本号，版本冲突时由服务端裁决。

第三是内容冲突的 UI 表达。两个人同时编辑同一个单元格，浏览器端和 Office 一样，需要展示"你的修改"和"对方的修改"并存的状态，让用户决定保留哪个。这块工作量和前面两步加起来相当可观，千万不要低估。

4.3 我建议的落地路线：先同步操作，再做选区和光标

如果团队是第一次做协同，我的建议是分两步走。

第一步，先做"段落级同步"：用户的修改通过 WebSocket 实时同步到其他人屏幕上，但不去处理选区和光标。这能解决 80% 的协同需求，实现起来相对可控。

第二步再加协作者光标和选区实时展示。这个依赖 Univer 的选区模型，每个用户把自己的选区位置（起始行列、结束行列）周期性地广播给别人，别人在画布上叠加渲染一个不同颜色的标志框。这里最麻烦的是选区在滚动、缩放、插入行列时的坐标校正，稍微漏一个场景就会出现光标漂移。

我的经验是，协同功能不要一上来追求完美，先把"对方改了，我能实时看到"跑通，再渐进式完善细节。这点想清楚之后，选型心态会稳定很多。

5. 实测中的坑：性能、内存与版本

这一节写的全是我在真实接入过程中踩过、并且已经填平了的坑。每一条都对应过一次真实的加班排查，拿出来分享给大家，希望能帮后来人省掉一些无谓的时间。

5.1 画布渲染不出来，第一反应检查容器高度

前面提过一次，但值得再展开。Univer 的 UI 插件初始化时会读取容器元素的尺寸来创建画布，如果容器高度为 0，它不会报错，只是渲染结果是一块空白。最常见的触发场景是：表格放在弹窗、折叠面板、Tab 切换页里，这些组件在初始化的瞬间往往还没有拿到真实高度。

解决办法有两个。一是在容器隐藏或未布局完成时不初始化 Univer，等它显示出来再创建实例。二是在容器尺寸变化后调用相关的重算接口，让渲染引擎重新计算画布尺寸。如果你用的是弹窗组件，而且弹窗里放表格，十有八九会遇到这个问题。

5.2 批量写入数据是性能的命门

前面提了 setValues 比 setValue 高效，这里补充一个反面案例。我最早写导入 Excel 功能时，拿了个 1 万行的数据循环逐格写入，页面直接卡死，控制台一片红色警告。改成按行构造二维数组、一次 setValues 后，同样的数据毫秒级完成。

更深一层的原因：每个写操作都会触发表格的重算和重绘。公式引擎要更新依赖链，渲染引擎要刷新画布，循环写就是把这套成本重复了一万次。所以凡是涉及大范围数据填充，一定要"攒一批，写一次"。这个思路也适用于自定义插件——尽量把你自己的逻辑也打包成一两条命令，而不是拆成一大堆细碎命令。

5.3 重复创建实例导致的内存泄漏

这是单页应用里最容易踩的坑。Vue 或 React 组件卸载时，如果只是把容器 DOM 删掉，Univer 实例挂载时的各种监听器、渲染循环、定时器其实还活着，再次进入页面时又创建一个新实例，内存占用会越来越高，最终整个应用卡顿。

解决方式也很简单，在组件卸载时调用销毁方法。不同版本销毁 API 名字略有差异，但思路一致：

onBeforeUnmount(() => { univerAPI.dispose(); });

如果你用的是预设版的 createUniverSheet，记得查一下它返回对象里的销毁方法。这一点文档里写得比较隐蔽，不少人中招。我当初就是在路由切换了几次之后发现浏览器内存暴涨，逐个排查监听器才发现是旧实例没有清理。

5.4 升级版本后 API 说没就没

Univer 还在 0.x 阶段，迭代非常快，语义化版本约束基本指望不上。我在接入期间经历过一次小版本升级，结果配置项名字变了，事件回调签名变了，折腾了一整天才把项目从报错海洋里捞出来。

所以这里给出三条实操建议：

• 一旦版本稳定运行，锁定精确版本号，不要用 ^ 或 ~ 范围依赖，避免 npm install 时悄悄升级到不兼容版本。
• 升级前先去官方仓库看CHANGELOG 和 migration 指南，确认有没有破坏性变更。
• 所有 Univer 相关代码集中封装在一个模块里，不要散落到各个业务组件。这样升级时只需要改一处适配层。

6. 二次开发：给自己的业务写一个公式和按钮

表格库做二次开发，最常见两类需求：一类是自定义函数，让公式引擎认识你公司的业务公式；另一类是在工具栏加按钮，接通你自己的导出、打印、提交审批流程。这两件事 Univer 都能做，而且因为它本身是插件化架构，做起来并不会对业务代码产生侵入。

6.1 自定义公式：让公司内部函数进表格

举个例子，电商业务里经常要算"到手价 = 原价 x (1 - 折扣率) - 平台扣点"。我们可以把它注册成公式 DISCOUNT_PRICE，业务方直接在单元格里写=DISCOUNT_PRICE(B2, C2, D2)。

import { BaseFunction } from '@univerjs/engine-formula'; class DiscountPrice extends BaseFunction { calculate(originalPrice: number, discountRate: number, platformCost: number): number { const price = Number(originalPrice) * (1 - Number(discountRate)) - Number(platformCost); return Math.max(0, price); } }

注册的方式根据版本略有区别，早期版本在注册公式引擎插件时传入函数列表，新版可能通过 API 直接注册。原理是一样的：你提供的类继承自 BaseFunction，返回计算值，公式引擎就能识别它，并纳入依赖链的求值流程。

依赖链是这里的关键词。自定义函数不只要"算出结果"，还必须在引用单元格变化时自动重算。Univer 的公式引擎会分析函数参数里引用的单元格区域，把它们登记为依赖。你只需要保证入参来自单元格引用，剩下的联动计算引擎会自动完成。这就是我前面说的，接入后很多功能像在搭积木。

6.2 往工具栏塞一个业务按钮

加按钮这类 UI 扩展，Univer 提供了菜单注册机制。以我在项目里新增"导出当前表"按钮为例，思路是在 UI 插件的菜单配置里注册一个菜单项，并绑定命令：

univer.registerPlugin(UniverSheetsUIPlugin, { container: 'app', menus: { 'secondary-bar': { 'export-sheet': { label: '导出当前表', handler: () => { const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook?.getActiveSheet(); exportSheetAsCsv(sheet); }, }, }, }, });

配置文件的具体结构不同版本有出入，但"通过菜单配置注入按钮"这个思路是稳定的。如果你需要更复杂的交互（比如点击按钮后弹出自定义表单），可以在命令内部调用你自己的业务组件，Univer 只负责把入口给你。

一个实用的建议：工具栏按钮别塞太多。用户是来用表格的，不是来欣赏工具栏的。我见过一些二次开发把十几个业务按钮全部堆上去，结果按钮找起来比 Excel 的菜单还难。保持克制，把最高频的几个动作放上去，其他的收进右键菜单或者自定义面板。

6.3 插件机制带来的想象空间

理解 Univer 的插件机制之后，你会发现它不只是"一个表格"，而是一个可以生长的办公平台。团队内部可以沉淀自己的插件库：客户管理表格插件、财务报表插件、项目排期插件，每个插件独立维护版本，组合使用。这种模式对中大型前端团队非常有吸引力，因为你不用为了新增一个业务能力就去改内核代码，团队协作的边界一下子就清晰了。

7. 最后说几句实在话

如果你正在为"在线表格"这件事选型，我的建议是：把 Univer 放进待调研清单里认真跑一遍 demo。尤其是那些已经决定投入 SAAS 化、需要长期迭代的团队，它的开源协议、架构前瞻性和社区活跃度，三项加起来几乎没有短板。当然也要做好心理准备：0.x 版本的 API 变化快，文档有时跟不上代码，很多细节要靠读源码和翻 issue 解决。但这恰恰说明项目在快速进化，试错成本是暂时的，长期被锁死在商业产品里的成本才是永久的。

最后再分享一个我在实际项目中养成的小习惯：接 Univer 这类框架，第一时间找到官方示例仓库里带完整代码的 demo，然后把它跑起来，再在此基础上做减法——先删掉你不要的功能，再逐步加入自己的业务逻辑。这样比从零啃文档快得多，也更容易避开那些藏在配置细节里的坑。