1. 从一张“只能填指定格子”的表格说起第一次接触 Univer 是在一个内部数据填报系统的需求评审上。业务方的诉求听起来特别朴素给一张类似 Excel 的表格让填报人只能改其中几列其他列锁死改完提交后台校验。当时团队第一反应是找个开源表格组件嵌进去结果试了几个方案都卡在同一个点上——要么是渲染性能撑不住几千行要么是权限控制粒度太粗没法做到“单元格级别”的锁定。后来有人甩了个链接过来就是 Univer。它的定位不是“又一个表格组件”而是一套前后端一体的表格与文档 SDK底层用 Canvas 做渲染对外暴露一套叫 Facade API 的高层接口同时提供 Node.js 侧的服务端能力。这几个关键词——univer、SDK、Node.js、Canvas、Facade API——基本就是它的技术骨架。我花了两周时间把它从 demo 跑到生产可用中间踩的坑不算少这篇就把整个落地过程拆开讲清楚。这篇文章适合几类人看正在做在线表格、协同编辑、数据填报类产品的前端或全栈想了解 Canvas 渲染引擎怎么撑起复杂表格的以及需要一套能同时跑在浏览器和 Node.js 里的表格内核的。哪怕你之前没听过 Univer看完应该能判断它到底适不适合你的场景。2. Univer 到底是什么为什么值得单独拿出来讲2.1 它解决的不是“显示表格”而是“表格内核”市面上大部分表格方案本质是“渲染 交互”的封装你拿到的是一个组件能显示、能编辑但一旦你要改它的行为逻辑比如自定义公式、自定义权限、自定义协同策略就得往源码里钻。Univer 的思路不一样它把表格拆成了几层底层是 Canvas 渲染引擎中间是数据模型和命令系统上层是 Facade API。你操作的是 API不是 DOM。这个分层带来的直接好处是同一套内核可以跑在浏览器也可以跑在 Node.js 服务端。浏览器里负责交互和渲染Node.js 里负责计算、校验、批量处理。比如你要做“用户只能填指定单元格”这个需求前端用 Facade API 把非填报区域设成只读后端用同一套 API 做二次校验逻辑是一致的不用写两遍。2.2 Canvas 渲染为什么是关键选择表格这东西行数一上去DOM 方案就顶不住。一万行 DOM 节点滚动直接卡成幻灯片。Canvas 的优势在于它只画“可视区域”滚动时重绘节点数量恒定。Univer 用 Canvas 做渲染配合虚拟滚动实测下来几万行的表格滚动依然跟手。但 Canvas 也有代价它没有 DOM 的天然可访问性和事件冒泡。所以 Univer 在 Canvas 之上自己实现了一套命中检测和事件分发你点击某个单元格它得先算出你点的是哪个格子再触发对应逻辑。这部分是它比较重的地方也是为什么它的包体积不算小。2.3 Facade API 的设计意图Facade 这个词本身就是“门面”的意思。Univer 内部有大量模块——渲染、公式、协同、权限、导入导出——如果每个模块都暴露一堆接口使用者会疯掉。Facade API 把这些能力收敛成一套统一的调用方式比如univerAPI.getActiveWorkbook()拿到当前工作簿然后.getActiveSheet()拿工作表再.getRange()拿区域链式调用下去。这种设计的好处是学习成本集中在一个入口坏处是灵活性受限于它暴露了什么。好在 Univer 的 Facade API 覆盖度还不错常见的单元格操作、样式、公式、冻结、合并都有权限控制也能通过它实现。3. 环境搭建Node.js 与 SDK 的配合3.1 Node.js 版本选择与安装Univer 的服务端能力依赖 Node.js官方推荐 18 以上我实际用的是 20 LTS。如果你机器上还没装去官网下载对应系统的安装包一路下一步就行。装完在终端敲node -v和npm -v能出版本号就说明成了。有个细节要注意如果你之前装过旧版本最好先卸干净再装新的不然可能出现node和npm版本不匹配的怪问题。Windows 上尤其容易残留卸载后手动检查一下环境变量里有没有旧的路径。CentOS 这类服务器环境用包管理器装可能版本太老建议用 nvm 或者直接下二进制包解压。我试过在 CentOS 7.9 上直接yum install nodejs装出来是 10.x跑 Univer 直接报语法错误。后来换成 nvm 装 20.x 才正常。3.2 项目初始化与依赖安装新建一个目录npm init -y生成 package.json然后装 Univer 的核心包。这里有个坑Univer 拆了很多子包比如univerjs/core、univerjs/sheets、univerjs/sheets-ui、univerjs/facade你得按需装。如果只是想跑个最小 demo装 core sheets facade 就够了。npm install univerjs/core univerjs/sheets univerjs/facade版本号建议锁死Univer 迭代比较快不同版本之间 API 可能有变动。我用的是一套 0.x 的稳定版具体版本号看官方 release 说明。3.3 最小可运行示例装完之后写一个最简单的入口文件创建一个 Univer 实例挂到一个 div 上然后往里面塞点数据。这一步的目的是验证环境通了别急着上复杂功能。import { Univer, LocaleType } from univerjs/core; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverFacadePlugin } from univerjs/facade; const univer new Univer({ locale: LocaleType.ZH_CN, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverFacadePlugin); const container document.getElementById(app); univer.createUniverSheet(container, { sheetData: { id: sheet1, name: 填报页, cellData: { 0: { 0: { v: 姓名 }, 1: { v: 部门 }, 2: { v: 工时 } }, 1: { 0: { v: 张三 }, 1: { v: 研发 }, 2: { v: } }, }, }, });跑起来能看到一个表格说明环境没问题。接下来才是重头戏——权限控制。4. 核心需求实现让用户只能填指定单元格4.1 需求拆解与技术选型回到最开始那个需求一张表用户只能改其中几列其他列锁死。拆开来看要解决三件事第一视觉上要能区分哪些能填、哪些不能填。通常做法是把只读区域设成灰色背景或者加个锁的图标。第二交互上要拦截。用户点到只读单元格不能进入编辑态就算通过粘贴、拖拽等方式想改也得被挡住。第三数据上要校验。前端拦截是体验后端校验是底线。用户绕过前端直接调接口提交后端必须能识别并拒绝。Univer 的 Facade API 里区域对象有setLocked或者类似的权限方法具体名字看版本。我用的版本是通过getRange().setEditable(false)来控制的。后端则用同一套 API 在 Node.js 里重建表格模型逐格校验。4.2 前端只读区域的设置先拿到工作表再拿到要锁的区域调只读方法。假设 A 列和 B 列是系统预填的C 列开始才是用户填的那就把 A、B 两列锁掉。const workbook univerAPI.getActiveWorkbook(); const sheet workbook.getActiveSheet(); // 锁定 A、B 两列索引 0 和 1 const lockedRange sheet.getRange(0, 0, sheet.getMaxRows(), 2); lockedRange.setEditable(false); // 给只读区域加个灰色背景视觉上区分 lockedRange.setBackgroundColor(#f0f0f0);这里getRange的参数是(startRow, startColumn, numRows, numColumns)注意别搞反。getMaxRows()拿当前最大行数如果后面动态加行得重新锁一次。4.3 拦截粘贴和拖拽的越界修改只读设置能挡住直接编辑但挡不住“从可编辑区域复制粘贴到只读区域”这种操作。Univer 有命令系统可以监听粘贴命令判断目标区域是否只读是就拦截。univerAPI.onCommandExecuted((command) { if (command.id sheet.command.paste) { const targetRange command.params.range; if (isRangeLocked(targetRange)) { // 抛出错误或静默取消 return false; } } });isRangeLocked需要你自己维护一份锁定区域的记录因为 Facade API 不一定提供“查询某区域是否只读”的方法。我的做法是在初始化时把锁定区域存到一个数组里拦截时遍历判断。4.4 后端 Node.js 侧的二次校验前端再怎么拦都不能信。后端拿到提交的数据后用 Univer 在 Node.js 里重建一个表格实例把原始数据填进去然后逐格对比只读区域的格子提交值和原始值是否一致不一致就拒绝。const { Univer } require(univerjs/core); const { UniverSheetsPlugin } require(univerjs/sheets); function validateSubmission(originalData, submittedData, lockedColumns) { for (const rowIndex in submittedData) { for (const colIndex in submittedData[rowIndex]) { if (lockedColumns.includes(Number(colIndex))) { const original originalData[rowIndex]?.[colIndex]?.v; const submitted submittedData[rowIndex][colIndex]?.v; if (original ! submitted) { return { valid: false, reason: 第 ${rowIndex} 行第 ${colIndex} 列不允许修改 }; } } } } return { valid: true }; }这段逻辑不依赖 Univer 也能写但用 Univer 的好处是数据模型一致公式、格式这些复杂情况也能覆盖。5. 实操中踩过的坑与排查记录5.1 常见问题速查表问题现象可能原因排查方向解决办法表格不渲染白屏容器没有宽高检查挂载 div 的 CSS给容器设明确宽高只读设置无效区域参数顺序错确认 getRange 参数按 startRow, startCol, numRows, numCols 传粘贴仍能改只读区未监听命令检查命令监听是否注册注册 paste 命令拦截Node.js 侧报模块找不到包未装全检查依赖列表补装 sheets、facade 等子包滚动卡顿行数过多未虚拟化确认是否开启虚拟滚动默认开启检查配置中文乱码locale 未设检查 Univer 初始化配置设 LocaleType.ZH_CN5.2 几个容易忽略的细节容器宽高必须明确。Canvas 不像 DOM 会自动撑开父容器没高度画布就是 0 高看起来就是白屏。我一开始用 flex 布局父级没设高度折腾了半小时才发现。区域索引从 0 开始。Excel 里 A 列是第 1 列但 API 里是 0。写代码时脑子里要转个弯不然锁错列。动态增行后要重新锁。如果表格支持用户新增行新增的行默认是可编辑的得在增行事件里重新对只读区域调一次锁定。后端校验要处理空值。用户没填的格子提交上来可能是 undefined 或空字符串和原始值的比较要统一处理不然会误判。5.3 性能调优的一点经验几千行的表格Univer 默认表现还行。但如果你的只读区域很大每次滚动都重绘灰色背景可能会有开销。我的做法是把只读区域的背景色通过样式表统一设置而不是逐格设减少重绘指令。另外命令监听里尽量做轻量判断别在里面做复杂计算。粘贴命令触发很频繁监听函数重了会拖慢整体响应。6. 这套方案还能怎么扩展Univer 的能力不止于表格。它还有文档、幻灯片的内核Facade API 也在持续扩展。如果你做完填报系统想加个“填报说明”的富文本区域可以直接用它的文档能力和表格共享同一套底层。协同编辑也是它原生支持的。多个用户同时填一张表Univer 有协同插件处理冲突合并。不过协同对后端要求高需要配套的协同服务这块我还没深入等后面有场景再补。导出 Excel 也是常见需求。Univer 有导入导出插件能把当前表格状态导出成 xlsx。实测下来格式保留得不错公式也能带出去。最后分享一个我在实际项目里的小技巧把锁定区域的配置抽成一个 JSON前端和后端都读同一份配置。这样改需求时只改一处不会出现前端锁了后端没锁的尴尬。配置大概长这样{ lockedColumns: [0, 1], editableColumns: [2, 3, 4], lockStyle: { backgroundColor: #f0f0f0 } }前端拿lockedColumns去设只读后端拿它去校验两边逻辑对齐维护起来省心不少。