有段时间我一直在头疼一个问题怎么在公司后台里放一个真正能用的表格。不是那种填填数据就算了的控件而是要能拖拽、能写公式、能合并单元格、能像在Excel里一样操作的在线表格。我试过各种自研方案、半成品库折腾到后头目光落到了univer这个还算年轻的开源办公套件上。当时它还没被很多人注意但我花了一晚上把Demo跑起来之后心里就冒出一个念头这东西才是正经做在线表格该有的底子。这篇文章就是想把我在业务系统里集成univer的完整过程、拆过的架构、踩过的坑和最后做出来的定制效果一次性说清楚。如果你也正打算给内部系统、SaaS平台或低代码产品嵌入表格能力这篇东西应该能帮你省掉不少探路时间。1. 为什么我会盯上Univer这个开源表格引擎1.1 三个真实痛点在逼我做技术选型先交代背景。我们当时要做的功能是“项目数据填报”用户要在浏览器里维护一套带格式、带公式、跨表引用的项目台账。第一版是后端生成HTML表格直接渲染只能看不能编辑后来换成input输入框能填了但完全扛不住合并单元格、条件格式这些需求再往后试了contenteditable方案那简直是给自己挖坑光标错位、粘贴格式失控维护成本高到离谱。所以要找一个真正的电子表格组件时我心里其实有三个硬性要求交互要接近Excel不是DatGrid那种单元格编辑器而是有列头行头、冻结窗口、拖拽填充、右键菜单的完整表格体验。必须能嵌入现有系统我们不能把整个业务页面交给一个黑盒组件需要它能放在一个div里跟我们自己的界面和平共处。数据要可控表格里的编辑要能触发我们自己的业务逻辑比如落库、校验、联动其他模块而不是把组件当作孤岛。带着这三个要求去选其实真正能打的就那几个。1.2 备选方案对比SpreadJS、Luckysheet、Handsontable和Univer我当时把市面的方案拉了个表逐项过了一遍。SpreadJS是最早被业务方推荐的功能确实全图表、透视表、数据绑定都有。但问题是授权模式复杂开发授权和部署授权分开来算按项目人头计费我们这种内部系统根本批不下来这个预算。Luckysheet很火GitHub星多界面也确实好看用起来很顺手。但它2019年左右进入维护放缓期代码分支多bug修得很慢我们集成到React项目里之后发现动态修改配置会触发整个表格重渲染操作一多明显卡顿特别是渲染几千行数据时滚动掉帧严重。Handsontable也试过它的强项是数据网格键盘导航和编辑体验都很好但本质上不是表格列宽行高、单元格合并、公式引用这些Excel语义弱很多。我们既要公式又要打印效果它也不太够。最后看到univer第一印象是“这组件怎么这么新”文档还在天天改但它的设计思路打动了我整个表格能力是拆成插件注册进去的渲染层用Canvas大幅度减轻DOM压力操作全部走命令总线。这个结构比我前面试过的那些库都更现代而且它自带公式引擎不是后面套上去的那种。综合下来我的判断是SpreadJS是“买了保险但肉疼”Luckysheet是“用着顺手但不敢依赖”univer虽然版本新但架构上限高社区也活跃值得赌一把。后面这一年多的事实证明这一把赌得还算值。2. 架构层先想明白命令系统、渲染和容器解耦集成第三方组件之前我习惯先把它的底层结构摸清楚不然出了问题只能瞎猜。univer的架构拆开来看其实分得很清晰。2.1 核心与Sheets分离本质是一个宿主框架你装包的时候会发现univerjs/core是所有模块的地基它本身不关心你做的是表格还是文档只管Univer这个宿主实例的生命周期、插件注册、依赖注入、命令分发和状态管理。真正的表格逻辑都在univerjs/sheets和univerjs/sheets-ui这两个包里前者是数据模型和业务算子后者是工具栏、右键菜单、输入框这些交互层。这个分层对我的意义很大。因为我只需要表格场景完全不需要把文档、幻灯片的能力一起打包进我的系统。按需注册插件最终产物体积是可控的。而且如果你想深度定制可以只保留sheets的底层能力自己重写一套UI外壳接口都是暴露出来的。Univer内部用了一个依赖注入容器类似Angular那种设计。扩展模块通过注册的方式把自己的服务注入到容器里在其他模块需要时再拿出来用。所以它天然的插件化不是表面功夫同一个核心可以挂载多个不同场景实例彼此互不干扰。2.2 渲染管线Canvas 2D 下的分层绘制这一点是univer性能能打的直接原因。传统表格组件用几千个div来一个格子一个元素地渲染行一多DOM爆炸操作就卡。univer的单元格区域用的是Canvas 2D绘制整个工作表相当于一张可局部更新的大画布。它内部做了一层层级管理单元格内容绘制到底层Canvas选区、边框、高亮这些交互层绘制在覆盖层Canvas再上层是DOM层用来承载输入框、下拉框等需要原生交互的控件。这样绘制和交互分离之后滚动时底图层基本只是位移重绘开销远小于重建DOM。更关键的是它会给每个单元格存一个渲染状态值叫SkipHash也好、脏标记也罢核心思想是绘制之前先比较当前状态和上次状态内容没变就直接跳过重绘。我实际测试过拖动滚动条浏览两万多行数据帧率相当稳定这也是我后来没有再去选别人的重要原因。2.3 全流程命令化为协同和撤销埋好了线如果你在univer里操作过你会发现每一次编辑、每一次选区变化其实都在走命令系统。比如“给A1单元格写入100”这个动作会构造一个set-cell-data命令经过命令服务校验、执行、生成反命令。这个模式带来的直接收益是撤销重做非常干净你不需要自己维护历史栈命令系统里天然有undo/redo。它对做协同也有好处协同本质上就是把本地的命令应用逻辑同步给远端远端的文档状态也能通过同样的命令重建。univer官方在协同方向上的规划也遵循这个思路虽然线上协同还没有完全像在线文档那么丝滑但底子是通的不是事后补。2.4 扩展单位插件还是插件在univer里你要加一个功能思考的单位就是“插件”。一个插件是一个类实现一组接口注册到Univer实例上。你可以通过插件拦截命令、订阅数据变化、增加自定义菜单按钮、渲染自定义单元格类型。对比我之前集成过的很多组件它们扩展功能是靠配置项堆出来的一旦配置项不够就得改源码。univer把扩展成本降到了写一个类再注册的层级。这个设计我后来用得非常顺手不少业务需求都能用插件方式干净地解掉不用动不动就fork仓库。3. 从空页面到能用的表格完整接入过程3.1 依赖安装与版本选择先提醒一句univer的版本迭代非常快API在不同版本之间变动很大。我现在写的这套是基于1.x版本的经验。如果你在网上搜到很老的帖子用的是univerjs/sheets、univerjs/sheets-ui这样逐个注册的写法注意那是旧版的用法。我用的是预设包一行引入内部的核心和sheet插件省事不少npm install univerjs/presets univerjs/presets-sheets之所以选择presets而不是直接装一堆散包是因为散包面临版本对齐问题core要跟sheets同步升级稍不注意就报类型错误。presets把依赖锁定好了从npm拉下来就是一套能跑的组队。3.2 创建Univer实例并挂载到容器创建一个表格实例核心代码比我预想的短很多import { Univer } from univerjs/presets; import { UniverPresetSheets } from univerjs/presets-sheets; const univer new Univer({ preset: UniverPresetSheets({ container: app, toolbar: true, }), });这段代码干了这几件事创建宿主实例注册表格数据模块注册交互UI模块然后指定把表格渲染到id为app的DOM节点里。它还会自动帮你加载默认工具栏包括合并单元格、对齐方式、字体、颜色这些高频操作。我大概跑通之后第一反应是“就这么简单”确实比起以前一个表格组件要写三十几项初始化config这个入口简洁太多了。不过这里有个容易踩的点container如果是空容器要给高度否则Canvas会拿到一个0高度的父容器表格可能直接不显示。我第一次就是忘了给高度白屏了半天还以为是包没装对。3.3 造数据给工作表里塞入业务数据光有空表格没用我们要把后端接口返回的数据写进去。通过Univer实例拿到当前激活的工作簿再取工作表就可以操作了const workbook univer.getActiveWorkbook(); const sheet workbook?.getActiveSheet(); const range sheet.getRange(0, 0, 3, 3); range.setValues([ [1, 2, 3], [4, 5, 6], [7, 8, 9], ]);这里getRange的参数是row、column、numRows、numColumns。注意它是从0开始的下标跟我们平时说的A1单元格在API里是(0,0)刚开始很容易搞混。如果要写单个单元格更推荐用命令方式后面讲协同和撤销时会发现这一层的好处import { SetRangeValuesCommand } from univerjs/sheets; await univer.commandService.executeCommand({ id: SetRangeValuesCommand.id, params: { range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }, value: { v: 你好, s: { b: true } }, }, });s是单元格样式对象的简写b代表加粗。这个参数结构在设置单元格样式时很常用可以先记住。3.4 工具栏配置控制哪些功能暴露给用户Univer的toolbar参数可以传boolean也可以传数组精细控制。我们内部系统不需要所有Excel功能我做了精简UniverPresetSheets({ container: app, toolbar: [ undo, redo, formatPaint, line, merge, ...[bold, italic, underline, strikeThrough], ], });配置项是字符串枚举值对应UI层注册的按钮。这种按需暴露的方式一方面让界面更干净另一方面也不用担心用户在对我们表格里误操作图表、透视表等我们用不到的功能。4. 业务系统中真正高频的功能落地4.1 嵌入式场景的事件监听把表格嵌入业务系统最核心的需求一般是用户编辑完单元格后我们的业务模块要能感知到变化。univer的事件API是插件里暴露的我常用的是单元格变更和选区变更const currentSheet univer.getActiveWorkbook()?.getActiveSheet(); currentSheet?.onCellChange((params) { const changedCell params.sheet.getRange(...); // 这里对接自己的业务校验逻辑 }); univer.getSelectionRender().onSelectionChange$.subscribe(() { // 获取当前选中的区域 });注意旧版本里onSelectionChange直接用即可新版本转到render层的流式订阅本质都是RxJS的Observable习惯了以后还挺顺手的。我们的做法的实际场景是当用户改了某个项目的“成本金额”列触发表单校验和汇总计算然后把结果直接写回另一个工作表的对应单元格。这个事件机制保证了前端能实时响应不用等用户点保存按钮。4.2 自定义公式让业务逻辑进表格Univer自带几百个常规公式但真正有价值的往往是自己定义函数。我们的系统里有一个“项目等级”字段根据基础数据里的区域、金额、周期三个维度算出一个等级。这个判断逻辑在服务端有我们也想在表格里展示一份方便用户边填边预览。自定义公式的写法是继承内置的函数基类import { BaseFunction, FUNCTION_NAMES } from univerjs/formula; export class ProjectLevel extends BaseFunction { override calculate(args: string[]) { const region args[0]; const amount Number(args[1]); const period Number(args[2]); let level D; if (region 华东 amount 1000000 period 12) { level A; } else if (amount 500000) { level B; } return level; } }注册倒不复杂在初始化时通过公式模块插件注册一下univer.getFormulaManager().registerFunction(FUNCTION_NAMES.USER, PROJECT_LEVEL, ProjectLevel);我在使用这个功能时最大的体会是把业务规则下沉到表格公式里业务人员能直接在单元格里看到实时结果并且公式本身是可看的不是黑盒。以后规则要调整前端会前部署新代码就行不需要重新生成整份数据文件。4.3 导入导出的落地方案业务系统里Excel导入导出是刚需。Univer本身的表情导入导出能力在不同版本中不一致我后来是这么组合的解析xlsx文件用SheetJS的xlsx库把数据转成Univer能识别的单元格结构然后用commands写入导出则反过来读取工作表数据后用xlsx库生成下载文件。这个方案虽然少了一些原生导出的便利但胜在稳定可控。我们还会导出一份PDF交给领导审批这步用了浏览器打印能力把表格区域构造为打印视图不算多完美但足够用。导入时一定要注意Excel的格式差异比如日期类型在Excel里是一个数字序列如果不做转换用户看到就是一串四万多的数字。类似这种边界情况我在上线前踩过几次后来总结成一张格式映射表见一张处理一张。4.4 主题定制跟自家前端风格对齐默认的蓝色主题挂在系统里很突兀。Univer的UI层基于CSS变量实现了主题定制改起来不难UniverPresetSheets({ container: app, toolbar: true, uiConfig: { theme: { primaryColor: #5B8FF9, textColor: #1F2329, }, }, });内部系统的主色是蓝紫色背景偏浅灰我把primaryColor和工具条背景色一调整体视觉就融合不少。如果想做夜间模式也可以把主题变量整体切换这个能力比改源码方式来得好维护。5. 集成中的坑从复现到修复的完整链路5.1 样式打架UnoCSS和字体带来的诡异白屏有一次表格在我们项目里完全渲染不出来控制台没报错DOM节点里什么都没有。我第一反应是版本问题排查一圈后发现不是。把Demo页面单独抽出来却能正常显示这就说明是和我们的全局样式冲突了。我们的项目在用UnoCSS做原子化样式全局reset规则把所有元素的box-sizing改成了border-box而Univer渲染的DOM层对某些容器类有宽度height的依赖buffer-box和content-box两种模式计算出来差了几个像素Canvas对出来的高度就变成了0。解决办法并不复杂给Univer挂载的容器包一层隔离.univer-host { all: initial; }另外还遇到过字体问题。Canvas绘制文字时用的是系统字体栈如果容器页面里没有Common字体个别字符会显示成方框特别是中文加粗。我们把UI层的fontFamily显式配成了系统里稳定的中文字体问题才消停。5.2 多实例与内存回收因为我们的系统是SPA路由切换时会销毁页面组件。但我发现Univer实例并没有随着组件卸载而清理每次进入页面再退出内存就涨一点。后来排查到是多实例没有手动销毁导致的。Univer提供了dispose接口const univer new Univer({ preset: UniverPresetSheets({ container: app }), }); // 组件卸载时 univer.dispose();但是要注意如果你的presets容器在创建时同时挂载了工具栏DOM只调用dispose可能还不够干净最好再手动移除容器内的子节点。我在封装的useUniver组件里做了两层清理dispose实例清空外部容器子元素。5.3 大数据量渲染卡顿的调试过程有一阵子填报超过一万行时输入时明显卡顿滚动也有掉帧。我开始怀疑Canvas渲染能力但细想不对因为Univer自己的Demo一开就是几万行都没问题。关键应该在我们的数据上。用DevTools Performance录了一会儿发现重绘时间主要集中在单元格内的富文本和条件格式判断上。原因是我们给每个单元格都塞了一套自定义格式对象即使内容没有变化渲染管线在比较渲染状态时也要序列化整个对象开销大。优化方式是给数据瘦身只给有格式差异的单元格设置样式其余统一用默认样式自定义的富文本尽量改用纯文本加样式字段。改完以后一万行数据输入延迟明显下降。这个经验其实适用于所有Canvas渲染型组件状态越简单SkipHash越有效率。5.4 版本升级的三连坑前面说Univer升级快这既是好事也是负担。我们中途从0.2.x升到1.x连续遇到三个问题第一个是初始化API整个变了旧版的registerPlugin逐个注册写法全部失效迁移到presets方案才算干净。 第二个是某些命令参数结构变了比如设置单元格样式的detail字段改成了range配置导致我们有一批封装函数要重写。 第三个是我们自定义插件里依赖的IRenderManager接口位置变了编译直接报错。我的经验是升级前先把自定义插件和命令参数列个清单逐项对照官方Changelog改升级后不要停在“能编译通过”这个标准要把高频操作全手点一遍确认交互没问题才能上生产。6. 基于插件机制做定制一个小案例6.1 定义场景业务填报里的“一键导入批次号”我们的台账每月要录入一批批次号从Excel里复制过来用户要么在单元格里一个个粘贴要么我们提前写死一个事件逻辑。我想做的是在工具栏加一个“批次导入”按钮点击后弹出一个输入框用户粘贴多行列文本Univer自动把内容按行列写入当前选区。6.2 用插件封装自定义命令先定义命令类型import { CommandType, type ICommand, type IExecutionContext } from univerjs/core; interface IImportBatchParams { batchText: string; } const IMPORT_BATCH_COMMAND_ID project.import-batch; export const ImportBatchCommand: ICommand { id: IMPORT_BATCH_COMMAND_ID, type: CommandType.COMMAND, handler: async (context: IExecutionContext, params: IImportBatchParams) { const sheet context.univer.getActiveWorkbook()?.getActiveSheet(); const rows params.batchText .split(\n) .filter((line) line.trim().length 0) .map((line) line.split(\t)); const selection context.univer .getSelectionRender() .getActiveRange(); const startRow selection.startRow; const startColumn selection.startColumn; const matrix rows.map((row, rowIndex) row.map((cellValue, colIndex) ({ startRow: startRow rowIndex, startColumn: startColumn colIndex, endRow: startRow rowIndex, endColumn: startColumn colIndex, value: cellValue.trim(), })) ); for (const row of matrix) { await context.univer.commandService.executeCommand({ id: SetRangeValuesCommand.id, params: { range: row[0], value: row[0].value }, }); } return true; }, };这样用户选中一个起始单元格粘贴多行数据、按Tab分割列命令就能自动把数据铺满整个区域。6.3 把命令挂到UI上命令有了还差一个UI入口。Univer的UI层支持在工具栏注册自定义按钮我们写了一个简单的按钮插件import { UniverPlugin, ToolbarButton } from univerjs/ui; export class BatchImportToolbarButton extends UniverPlugin { override onMounted(): void { this.registerUI(ToolbarButton, { id: batch-import-button, icon: DocumentArrowDownIcon, tooltip: 批次导入, onClick: () { const text window.prompt(请粘贴批次数据Tab分隔列Enter分隔行); if (!text) return; this.context.univer.commandService.executeCommand({ id: IMPORT_BATCH_COMMAND_ID, params: { batchText: text }, }); }, }); } }注册方式就是把这个插件和命令一起喂给Univer实例。整个过程做下来我觉得Univer的插件事务的体验是真的好。业务功能被分成了“命令UI插件”两个独立模块后续如果想上线协同命令改造加日志同步就行UI插件不用动。作为跟表格组件纠缠了一整年的人我最后想啰嗦几句实际的体会。Univer不是那种装完就能不管的库它的版本节奏快API变动频繁这就要求你始终关注它的更新文档。但正因为它一直在动一些原本缺失的能力比如移动端适配、协同编辑、更完善的打印都在陆续补齐。如果你只是要一个安安稳稳十年不改的表格组件它目前还不算那种选择如果你想把它嵌进自己的业务系统愿意花时间跟进它的迭代它给你的是一个上限很高的底座。我现在手上的项目已经离不开它了每天几千个填报任务的量级跑得稳也让我在处理类似需求时有底。 
长河君 · 2026/11/3 21:54:17 · 阅读 1.2k Univer表格引擎集成实战：从选型到业务功能落地
有段时间我一直在头疼一个问题怎么在公司后台里放一个真正能用的表格。不是那种填填数据就算了的控件而是要能拖拽、能写公式、能合并单元格、能像在Excel里一样操作的在线表格。我试过各种自研方案、半成品库折腾到后头目光落到了univer这个还算年轻的开源办公套件上。当时它还没被很多人注意但我花了一晚上把Demo跑起来之后心里就冒出一个念头这东西才是正经做在线表格该有的底子。这篇文章就是想把我在业务系统里集成univer的完整过程、拆过的架构、踩过的坑和最后做出来的定制效果一次性说清楚。如果你也正打算给内部系统、SaaS平台或低代码产品嵌入表格能力这篇东西应该能帮你省掉不少探路时间。1. 为什么我会盯上Univer这个开源表格引擎1.1 三个真实痛点在逼我做技术选型先交代背景。我们当时要做的功能是“项目数据填报”用户要在浏览器里维护一套带格式、带公式、跨表引用的项目台账。第一版是后端生成HTML表格直接渲染只能看不能编辑后来换成input输入框能填了但完全扛不住合并单元格、条件格式这些需求再往后试了contenteditable方案那简直是给自己挖坑光标错位、粘贴格式失控维护成本高到离谱。所以要找一个真正的电子表格组件时我心里其实有三个硬性要求交互要接近Excel不是DatGrid那种单元格编辑器而是有列头行头、冻结窗口、拖拽填充、右键菜单的完整表格体验。必须能嵌入现有系统我们不能把整个业务页面交给一个黑盒组件需要它能放在一个div里跟我们自己的界面和平共处。数据要可控表格里的编辑要能触发我们自己的业务逻辑比如落库、校验、联动其他模块而不是把组件当作孤岛。带着这三个要求去选其实真正能打的就那几个。1.2 备选方案对比SpreadJS、Luckysheet、Handsontable和Univer我当时把市面的方案拉了个表逐项过了一遍。SpreadJS是最早被业务方推荐的功能确实全图表、透视表、数据绑定都有。但问题是授权模式复杂开发授权和部署授权分开来算按项目人头计费我们这种内部系统根本批不下来这个预算。Luckysheet很火GitHub星多界面也确实好看用起来很顺手。但它2019年左右进入维护放缓期代码分支多bug修得很慢我们集成到React项目里之后发现动态修改配置会触发整个表格重渲染操作一多明显卡顿特别是渲染几千行数据时滚动掉帧严重。Handsontable也试过它的强项是数据网格键盘导航和编辑体验都很好但本质上不是表格列宽行高、单元格合并、公式引用这些Excel语义弱很多。我们既要公式又要打印效果它也不太够。最后看到univer第一印象是“这组件怎么这么新”文档还在天天改但它的设计思路打动了我整个表格能力是拆成插件注册进去的渲染层用Canvas大幅度减轻DOM压力操作全部走命令总线。这个结构比我前面试过的那些库都更现代而且它自带公式引擎不是后面套上去的那种。综合下来我的判断是SpreadJS是“买了保险但肉疼”Luckysheet是“用着顺手但不敢依赖”univer虽然版本新但架构上限高社区也活跃值得赌一把。后面这一年多的事实证明这一把赌得还算值。2. 架构层先想明白命令系统、渲染和容器解耦集成第三方组件之前我习惯先把它的底层结构摸清楚不然出了问题只能瞎猜。univer的架构拆开来看其实分得很清晰。2.1 核心与Sheets分离本质是一个宿主框架你装包的时候会发现univerjs/core是所有模块的地基它本身不关心你做的是表格还是文档只管Univer这个宿主实例的生命周期、插件注册、依赖注入、命令分发和状态管理。真正的表格逻辑都在univerjs/sheets和univerjs/sheets-ui这两个包里前者是数据模型和业务算子后者是工具栏、右键菜单、输入框这些交互层。这个分层对我的意义很大。因为我只需要表格场景完全不需要把文档、幻灯片的能力一起打包进我的系统。按需注册插件最终产物体积是可控的。而且如果你想深度定制可以只保留sheets的底层能力自己重写一套UI外壳接口都是暴露出来的。Univer内部用了一个依赖注入容器类似Angular那种设计。扩展模块通过注册的方式把自己的服务注入到容器里在其他模块需要时再拿出来用。所以它天然的插件化不是表面功夫同一个核心可以挂载多个不同场景实例彼此互不干扰。2.2 渲染管线Canvas 2D 下的分层绘制这一点是univer性能能打的直接原因。传统表格组件用几千个div来一个格子一个元素地渲染行一多DOM爆炸操作就卡。univer的单元格区域用的是Canvas 2D绘制整个工作表相当于一张可局部更新的大画布。它内部做了一层层级管理单元格内容绘制到底层Canvas选区、边框、高亮这些交互层绘制在覆盖层Canvas再上层是DOM层用来承载输入框、下拉框等需要原生交互的控件。这样绘制和交互分离之后滚动时底图层基本只是位移重绘开销远小于重建DOM。更关键的是它会给每个单元格存一个渲染状态值叫SkipHash也好、脏标记也罢核心思想是绘制之前先比较当前状态和上次状态内容没变就直接跳过重绘。我实际测试过拖动滚动条浏览两万多行数据帧率相当稳定这也是我后来没有再去选别人的重要原因。2.3 全流程命令化为协同和撤销埋好了线如果你在univer里操作过你会发现每一次编辑、每一次选区变化其实都在走命令系统。比如“给A1单元格写入100”这个动作会构造一个set-cell-data命令经过命令服务校验、执行、生成反命令。这个模式带来的直接收益是撤销重做非常干净你不需要自己维护历史栈命令系统里天然有undo/redo。它对做协同也有好处协同本质上就是把本地的命令应用逻辑同步给远端远端的文档状态也能通过同样的命令重建。univer官方在协同方向上的规划也遵循这个思路虽然线上协同还没有完全像在线文档那么丝滑但底子是通的不是事后补。2.4 扩展单位插件还是插件在univer里你要加一个功能思考的单位就是“插件”。一个插件是一个类实现一组接口注册到Univer实例上。你可以通过插件拦截命令、订阅数据变化、增加自定义菜单按钮、渲染自定义单元格类型。对比我之前集成过的很多组件它们扩展功能是靠配置项堆出来的一旦配置项不够就得改源码。univer把扩展成本降到了写一个类再注册的层级。这个设计我后来用得非常顺手不少业务需求都能用插件方式干净地解掉不用动不动就fork仓库。3. 从空页面到能用的表格完整接入过程3.1 依赖安装与版本选择先提醒一句univer的版本迭代非常快API在不同版本之间变动很大。我现在写的这套是基于1.x版本的经验。如果你在网上搜到很老的帖子用的是univerjs/sheets、univerjs/sheets-ui这样逐个注册的写法注意那是旧版的用法。我用的是预设包一行引入内部的核心和sheet插件省事不少npm install univerjs/presets univerjs/presets-sheets之所以选择presets而不是直接装一堆散包是因为散包面临版本对齐问题core要跟sheets同步升级稍不注意就报类型错误。presets把依赖锁定好了从npm拉下来就是一套能跑的组队。3.2 创建Univer实例并挂载到容器创建一个表格实例核心代码比我预想的短很多import { Univer } from univerjs/presets; import { UniverPresetSheets } from univerjs/presets-sheets; const univer new Univer({ preset: UniverPresetSheets({ container: app, toolbar: true, }), });这段代码干了这几件事创建宿主实例注册表格数据模块注册交互UI模块然后指定把表格渲染到id为app的DOM节点里。它还会自动帮你加载默认工具栏包括合并单元格、对齐方式、字体、颜色这些高频操作。我大概跑通之后第一反应是“就这么简单”确实比起以前一个表格组件要写三十几项初始化config这个入口简洁太多了。不过这里有个容易踩的点container如果是空容器要给高度否则Canvas会拿到一个0高度的父容器表格可能直接不显示。我第一次就是忘了给高度白屏了半天还以为是包没装对。3.3 造数据给工作表里塞入业务数据光有空表格没用我们要把后端接口返回的数据写进去。通过Univer实例拿到当前激活的工作簿再取工作表就可以操作了const workbook univer.getActiveWorkbook(); const sheet workbook?.getActiveSheet(); const range sheet.getRange(0, 0, 3, 3); range.setValues([ [1, 2, 3], [4, 5, 6], [7, 8, 9], ]);这里getRange的参数是row、column、numRows、numColumns。注意它是从0开始的下标跟我们平时说的A1单元格在API里是(0,0)刚开始很容易搞混。如果要写单个单元格更推荐用命令方式后面讲协同和撤销时会发现这一层的好处import { SetRangeValuesCommand } from univerjs/sheets; await univer.commandService.executeCommand({ id: SetRangeValuesCommand.id, params: { range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 }, value: { v: 你好, s: { b: true } }, }, });s是单元格样式对象的简写b代表加粗。这个参数结构在设置单元格样式时很常用可以先记住。3.4 工具栏配置控制哪些功能暴露给用户Univer的toolbar参数可以传boolean也可以传数组精细控制。我们内部系统不需要所有Excel功能我做了精简UniverPresetSheets({ container: app, toolbar: [ undo, redo, formatPaint, line, merge, ...[bold, italic, underline, strikeThrough], ], });配置项是字符串枚举值对应UI层注册的按钮。这种按需暴露的方式一方面让界面更干净另一方面也不用担心用户在对我们表格里误操作图表、透视表等我们用不到的功能。4. 业务系统中真正高频的功能落地4.1 嵌入式场景的事件监听把表格嵌入业务系统最核心的需求一般是用户编辑完单元格后我们的业务模块要能感知到变化。univer的事件API是插件里暴露的我常用的是单元格变更和选区变更const currentSheet univer.getActiveWorkbook()?.getActiveSheet(); currentSheet?.onCellChange((params) { const changedCell params.sheet.getRange(...); // 这里对接自己的业务校验逻辑 }); univer.getSelectionRender().onSelectionChange$.subscribe(() { // 获取当前选中的区域 });注意旧版本里onSelectionChange直接用即可新版本转到render层的流式订阅本质都是RxJS的Observable习惯了以后还挺顺手的。我们的做法的实际场景是当用户改了某个项目的“成本金额”列触发表单校验和汇总计算然后把结果直接写回另一个工作表的对应单元格。这个事件机制保证了前端能实时响应不用等用户点保存按钮。4.2 自定义公式让业务逻辑进表格Univer自带几百个常规公式但真正有价值的往往是自己定义函数。我们的系统里有一个“项目等级”字段根据基础数据里的区域、金额、周期三个维度算出一个等级。这个判断逻辑在服务端有我们也想在表格里展示一份方便用户边填边预览。自定义公式的写法是继承内置的函数基类import { BaseFunction, FUNCTION_NAMES } from univerjs/formula; export class ProjectLevel extends BaseFunction { override calculate(args: string[]) { const region args[0]; const amount Number(args[1]); const period Number(args[2]); let level D; if (region 华东 amount 1000000 period 12) { level A; } else if (amount 500000) { level B; } return level; } }注册倒不复杂在初始化时通过公式模块插件注册一下univer.getFormulaManager().registerFunction(FUNCTION_NAMES.USER, PROJECT_LEVEL, ProjectLevel);我在使用这个功能时最大的体会是把业务规则下沉到表格公式里业务人员能直接在单元格里看到实时结果并且公式本身是可看的不是黑盒。以后规则要调整前端会前部署新代码就行不需要重新生成整份数据文件。4.3 导入导出的落地方案业务系统里Excel导入导出是刚需。Univer本身的表情导入导出能力在不同版本中不一致我后来是这么组合的解析xlsx文件用SheetJS的xlsx库把数据转成Univer能识别的单元格结构然后用commands写入导出则反过来读取工作表数据后用xlsx库生成下载文件。这个方案虽然少了一些原生导出的便利但胜在稳定可控。我们还会导出一份PDF交给领导审批这步用了浏览器打印能力把表格区域构造为打印视图不算多完美但足够用。导入时一定要注意Excel的格式差异比如日期类型在Excel里是一个数字序列如果不做转换用户看到就是一串四万多的数字。类似这种边界情况我在上线前踩过几次后来总结成一张格式映射表见一张处理一张。4.4 主题定制跟自家前端风格对齐默认的蓝色主题挂在系统里很突兀。Univer的UI层基于CSS变量实现了主题定制改起来不难UniverPresetSheets({ container: app, toolbar: true, uiConfig: { theme: { primaryColor: #5B8FF9, textColor: #1F2329, }, }, });内部系统的主色是蓝紫色背景偏浅灰我把primaryColor和工具条背景色一调整体视觉就融合不少。如果想做夜间模式也可以把主题变量整体切换这个能力比改源码方式来得好维护。5. 集成中的坑从复现到修复的完整链路5.1 样式打架UnoCSS和字体带来的诡异白屏有一次表格在我们项目里完全渲染不出来控制台没报错DOM节点里什么都没有。我第一反应是版本问题排查一圈后发现不是。把Demo页面单独抽出来却能正常显示这就说明是和我们的全局样式冲突了。我们的项目在用UnoCSS做原子化样式全局reset规则把所有元素的box-sizing改成了border-box而Univer渲染的DOM层对某些容器类有宽度height的依赖buffer-box和content-box两种模式计算出来差了几个像素Canvas对出来的高度就变成了0。解决办法并不复杂给Univer挂载的容器包一层隔离.univer-host { all: initial; }另外还遇到过字体问题。Canvas绘制文字时用的是系统字体栈如果容器页面里没有Common字体个别字符会显示成方框特别是中文加粗。我们把UI层的fontFamily显式配成了系统里稳定的中文字体问题才消停。5.2 多实例与内存回收因为我们的系统是SPA路由切换时会销毁页面组件。但我发现Univer实例并没有随着组件卸载而清理每次进入页面再退出内存就涨一点。后来排查到是多实例没有手动销毁导致的。Univer提供了dispose接口const univer new Univer({ preset: UniverPresetSheets({ container: app }), }); // 组件卸载时 univer.dispose();但是要注意如果你的presets容器在创建时同时挂载了工具栏DOM只调用dispose可能还不够干净最好再手动移除容器内的子节点。我在封装的useUniver组件里做了两层清理dispose实例清空外部容器子元素。5.3 大数据量渲染卡顿的调试过程有一阵子填报超过一万行时输入时明显卡顿滚动也有掉帧。我开始怀疑Canvas渲染能力但细想不对因为Univer自己的Demo一开就是几万行都没问题。关键应该在我们的数据上。用DevTools Performance录了一会儿发现重绘时间主要集中在单元格内的富文本和条件格式判断上。原因是我们给每个单元格都塞了一套自定义格式对象即使内容没有变化渲染管线在比较渲染状态时也要序列化整个对象开销大。优化方式是给数据瘦身只给有格式差异的单元格设置样式其余统一用默认样式自定义的富文本尽量改用纯文本加样式字段。改完以后一万行数据输入延迟明显下降。这个经验其实适用于所有Canvas渲染型组件状态越简单SkipHash越有效率。5.4 版本升级的三连坑前面说Univer升级快这既是好事也是负担。我们中途从0.2.x升到1.x连续遇到三个问题第一个是初始化API整个变了旧版的registerPlugin逐个注册写法全部失效迁移到presets方案才算干净。 第二个是某些命令参数结构变了比如设置单元格样式的detail字段改成了range配置导致我们有一批封装函数要重写。 第三个是我们自定义插件里依赖的IRenderManager接口位置变了编译直接报错。我的经验是升级前先把自定义插件和命令参数列个清单逐项对照官方Changelog改升级后不要停在“能编译通过”这个标准要把高频操作全手点一遍确认交互没问题才能上生产。6. 基于插件机制做定制一个小案例6.1 定义场景业务填报里的“一键导入批次号”我们的台账每月要录入一批批次号从Excel里复制过来用户要么在单元格里一个个粘贴要么我们提前写死一个事件逻辑。我想做的是在工具栏加一个“批次导入”按钮点击后弹出一个输入框用户粘贴多行列文本Univer自动把内容按行列写入当前选区。6.2 用插件封装自定义命令先定义命令类型import { CommandType, type ICommand, type IExecutionContext } from univerjs/core; interface IImportBatchParams { batchText: string; } const IMPORT_BATCH_COMMAND_ID project.import-batch; export const ImportBatchCommand: ICommand { id: IMPORT_BATCH_COMMAND_ID, type: CommandType.COMMAND, handler: async (context: IExecutionContext, params: IImportBatchParams) { const sheet context.univer.getActiveWorkbook()?.getActiveSheet(); const rows params.batchText .split(\n) .filter((line) line.trim().length 0) .map((line) line.split(\t)); const selection context.univer .getSelectionRender() .getActiveRange(); const startRow selection.startRow; const startColumn selection.startColumn; const matrix rows.map((row, rowIndex) row.map((cellValue, colIndex) ({ startRow: startRow rowIndex, startColumn: startColumn colIndex, endRow: startRow rowIndex, endColumn: startColumn colIndex, value: cellValue.trim(), })) ); for (const row of matrix) { await context.univer.commandService.executeCommand({ id: SetRangeValuesCommand.id, params: { range: row[0], value: row[0].value }, }); } return true; }, };这样用户选中一个起始单元格粘贴多行数据、按Tab分割列命令就能自动把数据铺满整个区域。6.3 把命令挂到UI上命令有了还差一个UI入口。Univer的UI层支持在工具栏注册自定义按钮我们写了一个简单的按钮插件import { UniverPlugin, ToolbarButton } from univerjs/ui; export class BatchImportToolbarButton extends UniverPlugin { override onMounted(): void { this.registerUI(ToolbarButton, { id: batch-import-button, icon: DocumentArrowDownIcon, tooltip: 批次导入, onClick: () { const text window.prompt(请粘贴批次数据Tab分隔列Enter分隔行); if (!text) return; this.context.univer.commandService.executeCommand({ id: IMPORT_BATCH_COMMAND_ID, params: { batchText: text }, }); }, }); } }注册方式就是把这个插件和命令一起喂给Univer实例。整个过程做下来我觉得Univer的插件事务的体验是真的好。业务功能被分成了“命令UI插件”两个独立模块后续如果想上线协同命令改造加日志同步就行UI插件不用动。作为跟表格组件纠缠了一整年的人我最后想啰嗦几句实际的体会。Univer不是那种装完就能不管的库它的版本节奏快API变动频繁这就要求你始终关注它的更新文档。但正因为它一直在动一些原本缺失的能力比如移动端适配、协同编辑、更完善的打印都在陆续补齐。如果你只是要一个安安稳稳十年不改的表格组件它目前还不算那种选择如果你想把它嵌进自己的业务系统愿意花时间跟进它的迭代它给你的是一个上限很高的底座。我现在手上的项目已经离不开它了每天几千个填报任务的量级跑得稳也让我在处理类似需求时有底。