开源电子表格Univer集成实战：Canvas渲染与公式引擎的二次开发指南

这几年做企业应用，兜兜转转总是绕不过“在线文档”这道坎。客户要表格，要协同，要能嵌到自己的业务系统里，商业云文档又不让二次分发，于是大家开始找开源方案。Univer 就是我最近几个月高频使用的，一个能把电子表格直接嵌进 Web 系统、还自带公式引擎和协同能力的开源项目，底层是 Canvas 渲染，API 设计得很现代，社区活跃度也不错。这篇文章就把我实际接入和二次开发的经验整理出来，从架构到踩坑都聊一遍，给准备入坑或者正在筛选方案的同学一个参考。

1. 这到底是个什么：Univer 的定位和使用了什么技术

1.1 不是又一个表格组件，而是一套“办公基座”

很多人第一次看到 Univer 的 Demo，会以为它只是某个 Vue/React 表格组件的皮肤。但它的定位其实更像个“办公套件基座”：官方支持的插件不止是电子表格，还包括文档和幻灯片，底层共用一套渲染引擎和一套数据模型。也就是说，Univer 可以做成类似多人协作的在线 Office 入口，而不是单张表格孤岛。不过这中间最成熟、用户最多的还是电子表格模块，这也是我现在主要使用的。

它解决的典型问题有三类：第一，你需要在自研系统里提供一个“能编辑、能算数、能打印”的类 Excel 体验，而不是一坨静态数据展示；第二，你需要让多个用户在同一个文件上编辑，且能查看彼此的改动；第三，你需要能定制工具栏、权限、菜单、快捷键，让办公界面贴合业务，而不是反过来让业务去迁就通用表格的固定皮肤。

Univer 的技术核心是 TypeScript 写的，渲染不走 DOM 表格，而是用 Canvas 自绘。每一个单元格、行列头、选区都是画在 canvas 上的，这样做带来的最大好处是性能上限高，一次性渲染上万行、几十列时，DOM 表格早就卡成幻灯片了，Canvas 还能基本保持交互流畅。同时，Univer 把“交互 UI 层”和“业务数据层”拆得很干净，开发者可以只引入表格核心，然后按需挂上公式、协同、筛选等插件，而不是一锅端装所有功能。

1.2 版本、协议和社区现状

Univer 是开源软件，遵循 Apache 2.0 协议，这意味着你可以拿来商用、修改、分发，只要保留版权声明。对于很多公司来说，这一点比功能本身还重要，因为商业办公套件的授权费往往高得离谱，而且不同终端、不同用户数都分别计价。

目前 Univer 的发布节奏已经稳定，项目维护者在 GitHub 上的响应速度也还可以，Issues 区能看到不少真实企业用户反馈的问题。社区里流传的资料主要分英文文档和中文社区两种，中文资料相对少一些，但项目官方有自己的文档站和示例库，基本够用。社区里搜“univer”能搜到的主要是入门案例和踩坑记录，官方文档则更适合从 0 到 1 搭建。

我自己的使用版本基于当前的 releases 主线。这里要提醒一句：Univer 处于快速迭代期，API 偶尔会不兼容，你如果在大版本之间升级，一定要看迁移文档，别盲目替换依赖。曾经遇到一个小版本把createUnit的参数结构改了，团队其他人没看变更说明，结果跑起来报一堆类型错误。

2. 为什么值得认真考虑：Univer 的核心能力拆解

2.1 数据、逻辑、UI 三层分离的设计

我第一次看 Univer 源码时有点意外：它不像很多表格组件那样，组件内部包着所有状态，而是借用了类似游戏引擎和办公软件混合的思路——渲染引擎、公式引擎、协同服务各自独立，通过定义良好的接口协作。

具体来说，Univer 大致分成这几层：

• 数据模型层：管理工作表、单元格值、样式、行高列宽等原始数据，这部分像是后端数据库里的表结构，不关心怎么画。
• 渲染引擎层：负责把数据模型映射到 Canvas 上，包括在网格上的绘制、文本绘制、选区高亮、滚动区域裁剪等。
• 交互层：处理鼠标、键盘、触摸事件，把用户操作翻译成命令。
• 命令/事务层：用户任意一次操作，比如输入值、合并单元格、设置边框，都会被封装成一个 command，记录到操作栈里。这为撤销重做和协同都提供了一致的基础。

这种分层带来一个很实际的收益：你可以替换掉某一部分而不影响整体。比如你不喜欢 Univer 默认的深色主题，可以只改设计变量；你想让公式引擎独立跑在 Web Worker 里，也可以在命令层做封装，而不需要把渲染层拆掉。

2.2 公式引擎：合规且可扩展的计算底层

公式是表格软件的灵魂。Univer 内置了较完整的公式引擎，支持常用的数学、统计、文本、日期等函数，也能处理跨工作表引用，例如=SUM(Sheet2!A1:A10)。它还有一个很关键的“Recalculation”机制：当单元格值变化时，公式依赖的单元格会自动标记为脏，然后在下一帧统一重算，避免每改一个值就全表计算。

对我来说，公式引擎真正值钱的不是内置函数数量，而是它有一棵清晰的 AST（抽象语法树）和解析器。如果你要扩展自定义函数，比如实现行业内的复利计算、加班工时换算，可以直接注册一个函数定义，然后在公式里使用。这个扩展方式类似 Excel 的 UDF（User Defined Function）机制，只是换成 TypeScript 实现。

不过也要注意，Univer 的公式引擎目前不是 100% 兼容 Excel，在极端复杂函数、数组公式、循环引用处理上可能跟 Excel 有细微差异。做原型还好，如果业务涉及大量遗留 Excel 公式，建议在项目初期跑一遍公式兼容性测试库，把常用公式都覆盖到，尤其是财务和统计需求多的企业。

2.3 协同编辑：可以只接服务端也能自己实现

Univer 的协同是基于操作日志游程的。两个客户端之间不传输整个表格快照，而是传输每个用户的操作指令，也就是上面的命令层产物。每个客户端在执行命令后，会把命令通过通信通道发给其他端，其他端在自身数据模型上重放同样的命令，从而实现同步。

这样做的好处是网络占用低，一个单元格改文本的命令可能只有几十字节。也正因如此，Univer 协同对网络通道的要求不高，WebSocket、Socket.IO、甚至类似 Matrix 的协议都可以接。官方文档提供了协同编辑的示例实现，默认是使用一套自己的协议栈，你如果不想自己折腾，可以直接用官方集成的协同服务；如果你想自建，则需要把“命令传输-冲突处理-游标同步-状态还原”这套链路实现完整。

我在实际项目里没有直接启用官方协同，而是先把单机版嵌入到了内部后台，第二步才接协同服务。因为协同引入的不只是通信代码，还有在线状态、权限控制、历史版本回滚。这些交互细节如果第一次直接上，业务方很难把控体验。建议你先明确协同是核心卖点还是附属功能，再决定投入。

3. 亲手把它跑起来：快速接入的完整实操过程

3.1 用包管理器初始化项目

我演示的环境是基于 Vite + TypeScript，如果你用 Vue 或原生 JS，思路一样。先创建项目：

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

接着安装 Univer 相关依赖。Univer 采用了模块化 npm 包结构，核心包和 UI 包分得很细。最省事的方式是安装官方预设包：

npm install @univerjs/presets @univerjs/presets-sheets

如果你更想按需加载，可以分别安装@univerjs/core、@univerjs/sheets、@univerjs/ui、@univerjs/engine-render、@univerjs/engine-formula等，但这种模式需要你自己装配，入门成本较高。我建议第一版先全部用预设，跑通以后再用 Tree Shaking 消减体积，避免一开始就被依赖关系绕晕。

3.2 创建并渲染一个表格实例

在src/main.ts（或入口文件）里写如下代码：

import { Univer } from '@univerjs/presets'; import { UniverPresetSheets } from '@univerjs/presets-sheets'; const univer = new Univer({ presets: [ new UniverPresetSheets({ ui: { container: 'app', toolbar: true, }, }), ], });

这个Univer实例就是整个应用的门面。UniverPresetSheets这个预设会帮我们装好表格渲染、Ribbon 工具栏、单元格编辑、公式解析等基础能力。容器可以指定页面上的一个 DOM 元素，比如 id 为app的 div。

然后再创建具体的工作簿：

import { UniverInstanceType } from '@univerjs/core'; univer.createUnit(UniverInstanceType.SHEET, { name: 'Demo', sheetOrder: ['sheet-01'], sheets: { 'sheet-01': { id: 'sheet-01', name: 'Sheet1', rowCount: 200, columnCount: 50, cellData: { 0: { 0: { v: '单价', s: { bl: 1, bg: '#f5f5f5' }, }, 1: { v: '数量', s: { bl: 1 }, }, 2: { v: '小计', s: { bl: 1 }, }, }, 1: { 0: { v: 10, }, 1: { v: 3, }, 2: { f: 'A2*B2', }, }, }, }, }, });

注意上面的cellData格式：行索引和列索引都从 0 开始，v表示原始值，s表示单元格样式，f表示公式。这里我们做了一个小 Demo：A2 是 10，B2 是 3，C2 是公式A2*B2，运行后 C2 会显示 30。

一个常见的困惑是：为什么既要createUnit又要在new Univer时传入预设？简单说，Univer管理运行时环境，相当于操作系统；createUnit创建具体文档实例，相当于打开某个文件。这样一套环境可以创建多个表格文件，也可以在同一页面创建不同类型文档，适合以后做多标签页办公套件。

3.3 把数据库里的 JSON 数据塞进表格

真实场景下，你肯定不是手动写死的单元格数据，而是从后端接口拿数据后渲染到表格上。可以直接把接口返回的二维数组转换成cellData的嵌套结构。为了省事，可以先写一个转换函数：

function arrayToCellData(headers: string[], rows: unknown[][]) { const cellData: Record<string, Record<string, { v: unknown; s?: object }>> = {}; headers.forEach((header, colIndex) => { cellData[0] = cellData[0] || {}; cellData[0][colIndex] = { v: header, s: { bl: 1, bg: '#f0f0f0' } }; }); rows.forEach((row, rowIndex) => { row.forEach((cell, colIndex) => { cellData[rowIndex + 1] = cellData[rowIndex + 1] || {}; cellData[rowIndex + 1][colIndex] = { v: cell }; }); }); return cellData; }

然后把返回的 JSON 转成该结构后传给createUnit。我建议把创建单元的代码封装成一个函数，方便后续动态切换不同数据源：

function loadSheet(data: { name: string; rows: unknown[][]; headers: string[] }) { const cellData = arrayToCellData(data.headers, data.rows); // 移除旧实例避免重复创建 // 这里用 univer.getCurrentUnit() 判断并销毁旧文件 const oldUnit = univer.getCurrentUnit(); if (oldUnit) { univer.disposeUnit(oldUnit); } univer.createUnit(UniverInstanceType.SHEET, { name: data.name, sheetOrder: ['sheet-01'], sheets: { 'sheet-01': { id: 'sheet-01', name: 'Sheet1', rowCount: data.rows.length + 10, columnCount: data.headers.length, cellData, }, }, }); }

这里有个容易踩的坑：重复创建同一个名称的工作簿，Univer 不会自动清理旧实例。如果你在单页应用里切换菜单，不断createUnit，页面上的表格区域就会叠加出多个透明 Canvas，表现为“出现多个表格重叠”。正确做法是先拿到当前单元并disposeUnit，或者直接用 SDK 提供的“载入快照”能力替换内容，而不是反复创建新实例。

3.4 页面里放哪些必备配置项

如果你的使用场景是给内部运营人员做数据录入，工具栏可以保留，但需要调整默认功能。Univer 的预设里暴露了比较全的配置入口，比如你可以通过ui配置项控制菜单项、工具栏按钮显隐：

new UniverPresetSheets({ ui: { container: 'app', toolbar: true, menu: { file: { export: true, print: true, }, insert: { image: false, }, formula: { functionList: true, }, }, }, })

实际配置名以官方文档为准，这里我的意图是说明：你可以把不少无关按钮先藏掉，让界面看起来更聚焦。注意，Univer 很多动作是先经过“命令”的，即使按钮隐藏了，也可以通过键盘快捷键触发，所以严格的权限校验还是要在业务层自己做，单纯隐藏 UI 不是安全手段。

4. 把 Univer 变成你自己的：核心定制和开发实践

4.1 自定义工具栏按钮

企业内部经常需要一个“保存到服务端”的按钮。Univer 自带的是基于浏览器本地存储的草稿，或者通过协同服务持久化。但在普通管理系统里，我们更希望在点击“保存”时，把当前整个工作簿的快照发送到我们自己的后端接口。

Univer 提供了registerDomain或者通过injector来注册自己的命令和 UI。简单做法：先在渲染出来的 Ribbon 工具栏上配置自定义按钮，在点击回调里用univer.getCurrentUnit()拿到当前工作表单元，调用它的快照接口获取数据，再发请求。

伪代码如下：

const currentUnit = univer.getCurrentUnit(); const snapshot = currentUnit.getSnapshot(); const workbookData = JSON.parse(snapshot); // 然后 POST 到后端 fetch('/api/sheet/save', { method: 'POST', body: JSON.stringify({ name: workbookData.name, sheets: workbookData.sheets }), });

get 到的快照是包含表格数据、样式、行列配置的完整 JSON 结构。你可以把它原样存到数据库里，下次要打开时再通过createUnit传回去。需要注意的是，快照里可能包含一些内部字段，存储时可以原样存，但如果你要让后端系统去读取具体单元格值，最好自己在服务端写解析函数，而不是依赖快照内部格式。

4.2 自定义单元格渲染

Univer 虽然整体是 Canvas 渲染，但允许你在单元格内注册自定义渲染器。比如你想把某一列的“状态”字段渲染成圆点加文字，而不是普通文本，就可以实现一个单元格渲染器。

这个功能基于注册表模式，大约是这样：

import { CustomCellRender } from '@univerjs/engine-render'; class StatusCellRender extends CustomCellRender { drawCellContent(ctx, info) { const { data, x, y, width, height } = info; // 先画圆点 ctx.fillStyle = data.color || '#00aaff'; ctx.beginPath(); ctx.arc(x + 10, y + height / 2, 4, 0, Math.PI * 2); ctx.fill(); // 再调用父类画文字 return super.drawCellContent(ctx, { ...info, data: { ...data, v: data.label ?? data.v }, }); } }

实际 API 可能随版本变迁，但思路是对的。自定义渲染要尤其注意性能：不要在drawCellContent里做复杂计算，因为滚动时 Canvas 会频繁重绘这些单元格，复杂逻辑会直接拖慢帧率。我的经验是，把需要自定义绘制的区域尽量限定在可视区，通过range条件控制，只对特定列启用。

4.3 接入你的后端权限体系

表格软件在系统集成中最难的不是渲染，而是权限。比如某些列只有经理能看到，某些单元格不可编辑，需要根据当前登录人判断。Univer 有两种做法配合：

一种是靠数据层控制：在渲染前，根据用户权限过滤掉敏感字段，再传给表格。但这种方法会导致“同一份数据需要生成多份快照”，后端存储也会比较麻烦。

另一种是靠交互层控制：保留完整数据，但通过 Univer 的编辑事件把非法的变更“拦截”下来。比如监听beforeChange或在命令执行管线的前端设置一个拦截器，当发现当前用户对目标选区没有编辑权时，就取消执行命令。

我在实际项目中使用的是拦截器思路中偏简单的版本：先禁用右键菜单的“粘贴”，再监听onCellChange，等单元格值变化后校验权限，如果校验失败就把数据回滚到修改前。这个方案在体验上不算最优，因为用户会看到值闪了一下然后变回去，但胜在实现简单、逻辑清晰。追求更好体验的同学可以自己去深入命令管线，在命令生效前就挡住。

4.4 公式扩展：自定义一个业务函数

假设业务要求“根据员工工龄计算带薪年假天数”。Excel 里没有现成，我们可以注册一个WORK_YEARS函数。

Univer 的函数注册入口大概是这样：

import { FormulaEngineService, operatorToken } from '@univerjs/engine-formula'; const formulaEngine = univer.__getInjection(FormulaEngineService); formulaEngine.registerFunction('ANNUAL_LEAVE', (year: number) => { if (year < 1) return 0; if (year < 10) return 5; return 10; });

之后用户在单元格里输入=ANNUAL_LEAVE(5)就会得到 5。扩展函数时要注意参数顺序和类型，Univer 公式引擎会按尝试类型转换，如果传进来的参数是字符串，最好自己多写几个判断或者用“公式重算引起的”参数类型做兼容处理。我踩过坑是注册的函数名跟内置函数冲突，导致后续公式计算结果异常，所以注册自定义函数时一定先看看函数清单里有没有同名。

5. 别等上线再后悔：生产中必须要注意的事项

5.1 性能优化从数据量开始

前面提到 Univer 基于 Canvas 渲染，滚动列表的性能比 DOM 表格好很多，但也不是无限大。我做了一个 10000 行 × 20 列、每列都有样式和部分公式的测试，初始渲染大概需要 2 秒左右，滚动操作没有明显掉帧。如果把数据再拉大，比如 5 万行，并且每行都套公式，浏览器主线程的压力就上来了。

优化策略其实和通用前端性能优化一样，核心原则是“减少重算范围”。具体措施包括：

• 公式引用范围精确定位，不要整列求整列，例如=SUM(A:A)这种写法会让公式引擎计算量暴增，改成=SUM(A1:A1000)。
• 大表格中临时隐藏复杂行，通过数据模型设置行过滤。
• 把只读场景和编辑场景分开：如果需要展示 5 万行数据，可以用静态 Canvas 列表平铺，不一定非得挂完整的公式引擎。只有在真正需要输入和计算时启用完整表格。

5.2 网络传输和协同冲突的坑

接入协同后，最容易出问题的是“先把本地修改发给远端”还是“先应用命令再发”。Univer 的推荐流程里，命令是先在本端执行，再广播给其他端。但如果某个命令依赖上下文的选区状态，而其他端数据已经不同，重放时可能报错。这个时候你要检查是否为命令携带了完整上下文，或者采用类似 OT 的转换逻辑。

我实测下来，Univer 协同服务处理文本经典的“同时在某行插入字符”这类并发冲突相对可靠，但对于合并单元格、插入行列等结构性操作，协同稳定性还在完善中。如果你要上线正式的协作编辑功能，一定不能只做单人测试，至少用 3 个浏览器开同一份表格互相改动，重点测并发插入行、插入列、修改同一单元格公式。

5.3 样式和字体兼容

Univer 的 Canvas 文本绘制依赖浏览器本地字体。如果你指定了系统不存在的字体，Canvas 会回退到默认字体，导致表格中的内容和 Excel 里显示的不一致。尤其中文字体，Windows、macOS、Linux 字体库差别很大，强烈建议在 CSS 里定义完整的字体栈：

body { font-family: "PingFang SC", "Microsoft YaHei", "Source Han Sans SC", Arial, sans-serif; }

另外，复制粘贴到 Excel 的体验也要注意。Univer 支持的剪贴板格式需要和浏览器权限配合。如果页面放在 iframe 里且没有开启“剪贴板权限”，用户可能无法粘贴 Excel 中带格式的数据。这个问题常见于嵌入式后台系统，需要给 iframe 添加allow="clipboard-read; clipboard-write"。

5.4 打包体积和按需加载

Univer 是个大项目，初始包体积不算小。使用全量预设时，构建后的 JS 可能在 1MB 以上（gzip 后几百 KB）。对于后台系统问题不大，但如果放到了面向 C 端用户的门户页面，就需要注意首屏性能。

做法是分模块加载：首屏只加载渲染引擎、核心表格模块，公式引擎和协同模块在用户点击“显示公式”或者登录协同服务时才按需 import。官方提供了较完整的模块拆分，配合 Vite 的动态 import 可以做到只加载需要的部分。千万不要为了省事，把一个公用的univer依赖放到所有页面的公共 chunk 里，那样会让整个系统的首屏都背上一份沉重的负担。

6. 常见问题速查与我在实战中的替代方案

6.1 常见错误和解决办法

我整理了几个高频问题，都是团队里后来接手的人反复遇到的。

6.2 一些更好用的替代方案对比

在很多技术选型讨论里，大家会问“Univer 和 Luckysheet 怎么选”“和 Handsontable 怎么选”。我的看法是：

• 如果只是简单的表格展示、内联编辑，要小于 100KB 而且不需要公式，那原生的 HTML Table 或轻量表格库就够了，没必要引入 Univer。
• 如果明确需要 Excel 级体验，比如合并单元格、跨表公式、条件格式、冻结行列，那 Univer 和 Luckysheet 都在范围内。Univer 的现代架构和社区活跃度更好线，新版 Luckysheet 则相对更成熟稳定，但二次开发时改起来更费劲。
• 如果只需要数据网格用于业务系统 CRUD，Handsontable 是老牌选择，文档丰富，但受商业许可证限制，必须注意协议。相比之下 Univer 的 Apache 2.0 更自由。
• 如果是想快速做一个协作文档而不是自建数据系统，那直接用成熟的在线协作文档产品反而更划算，折腾 Univer 协同需要额外成本。

我自己现在的选型标准很简单：需要公式引擎就优先 Univer，需要协作且团队有后端能力就选 Univer，否则切到更轻量的方案。技术选型没有全能，只有合适。

6.3 关于“在 Vue3/React 里怎么封装”的心得

Univer 是框架无关的，它只是一个 TS 库，管理自己的 DOM 容器，并不依赖生命周期。但如果你在 Vue 里使用，强烈建议封装成一个自定义组件或者 composable，而不是在每个页面里裸写初始化和销毁逻辑。

我用 Vue 3 封装时的核心逻辑大概是：

// useUniver.ts import { onBeforeUnmount, onMounted, ref } from 'vue'; import { Univer } from '@univerjs/presets'; import { UniverPresetSheets } from '@univerjs/presets-sheets'; export function useUniver(containerRef) { const univer = ref<Univer>(); onMounted(() => { univer.value = new Univer({ presets: [new UniverPresetSheets({ ui: { container: containerRef.value } })], }); }); onBeforeUnmount(() => { if (univer.value) { univer.value.dispose(); } }); return univer; }

这样做的好处是组件的复用性好，页面卸载时不会残留 Canvas 实例和事件监听。如果你在 React 里，思路完全一样，只需要把生命周期换成useEffect。

6.4 我实际生产环境中走过的弯路

最后一次补充几个我个人的体会。

第一，不要在初始化阶段把所有插件全开。Univer 提供的能力多，但每一种能力都需要计算资源和内存。生产环境建议按业务模块拆分成不同入口，例如“只读报表入口”不加载编辑插件，“数据录入入口”只加载编辑和基础公式，“分析入口”才加载全套分析功能。

第二，保存功能不要直接从快照里拿文件覆盖所有单元格。我一开始直接从getSnapshot拿整个表丢给后端，用户数据少还好，数据多时快照里有大量样式和行高列宽信息，传输量大、保存慢。后来改成只存业务数据字段，把样式相关的字段单独在做皮肤配置，这样接口传输小了大概 70%。

第三，联动业务系统时尽量用“命令”而不是“直接改数据”。很多场景是用户点击一个按钮，需要同时更新表格多个区域的数值。你看见 Univer 的公开 API 里有setCellValue之类的方法，可以直接对单元格赋值，但这种方式走不到“撤销/重做”流程里。如果业务允许撤销操作，那么要用官方提供的 Command 方式，而不是直接改内部数据。

我个人的习惯是：给每个业务动作都封装成“注册命令 + 触发命令”两层，最后统一通过命令执行单元操作。这样用户无论手动输入，还是点击系统按钮，都走同一套变更通道，撤销重做逻辑也自然兼容。

7. 这个方向还能怎么延伸

Univer 目前其实可以承载很多更重的办公场景。如果你用的版本较新，可能还能看到它们在做公式追踪、命名区域、图表、透视表等功能。从实际项目角度，我后续会优先尝试把 Univer 作为低代码平台里的“报表单元格”基础组件，让业务人员通过简单拖拽，把数据库字段映射到表格模板中。这样业务人员维护一个配置，系统就能自动生成一张带公式的可填写表单，落地速度会比传统开发的报表功能快不少。

我个人在实际操作中的体会是：不要用老思维去使用它，把它当成一个可拆装的办公内核，才能真正释放出价值。如果你也打算做类似的集成，建议先写一个最小的可运行 Demo，把数据读取、渲染、保存、二次加载走通，再考虑后续的权限和协同。这套流程只要跑通，后面的定制就会顺很多。这个方向往后还可以接智能表格、数据透视、报表打印等，能做的事挺多。