Univer在线表格引擎：实现单元格锁定与数据验证的限填表方案

做在线表格最头疼的事，不是把Excel搬到网页上，而是怎么让一张表既能让用户填，又不能让用户改坏。我见过太多项目在“只读”和“可编辑”之间二选一：要么整张表只读，需求方说“那我怎么填数据”；要么全表可编辑，运营同事一个误操作就把生产数据覆盖了。univer这个开源项目，是我最近测下来比较能同时解决这两件事的方案。它本质上是一个基于TypeScript的在线表格引擎，但它在“工作表保护、单元格锁定、数据验证”这套机制上做得相当完整，特别适合做成“管理员定义表格模板、指定单元格让用户填写、其余单元格不可修改”这类业务场景。如果你正在做数据填报、任务派发、审批台账、客户信息采集这类系统，大概率会遇到这张“用户能写但写不乱”的表格，这篇就从需求拆解、设计思路、实操落地到踩坑经验，完整聊聊我个人的做法。

1. 需求拆解：为什么“填表格”和“改表格”必须分开

1.1 一张“限填表”背后到底藏着什么诉求

拿我实际做过的客户信息登记来举例。业务方最初提的需求很简单：给我一个表格，让销售自己填客户资料。听起来很容易，但真把一张Excel文件丢到群里，问题立刻就来了。有人顺手改了表头，把“客户名称”改成了“公司名称”；有人误删了“客户编号”列，后面所有人的编号对不上了；有人把带公式的“登记日期”单元格直接粘贴成了静态文本；还有人在“意向等级”里自由发挥，填了“A+”“很有意向”这类枚举之外的脏数据。

于是需求就变成了：“这张表的结构必须保留，销售员只能改姓名、电话、备注这几个格子，其他区域一律不能动。”这就是“用户定义表格 + 限填单元格”的真实诉求。它不只是权限控制，而是把一张表按角色划分成了多个区块：表头、说明、公式计算区属于模板所有者；数据录入区属于填报者；审核修正区又可能属于另一拨人。univer在这条线上做得比较顺手，因为它的数据模型里原生就有“工作表保护（protection）”“单元格锁定（locked）”“数据验证（data validation）”这些概念，不用像普通前端表格库那样，自己拿代码去拦截编辑事件、再手动回滚值。

1.2 传统方案的三个痒点

先说说为什么不能直接用现成的表单工具或通用在线文档。表单工具在“字段模型”上很强大，但做不了“一张二维表格里既有模板又有明细”的灵活度。通用的在线文档协作平台虽然支持多人编辑，但权限是整表级的，最多做到“可查看”或“可编辑”，没法在同一个工作表里精确到某列可写、某列只读、某列必须通过公式算出结果。再退一步，自己用div加input去渲染表格，数据量到几千行就开始卡，更别谈公式联动、撤销重做、数据校验这些Excel级基础能力。

所以当我把univer放进候选项时，最看重的就是它保留了Excel的语义层：单元格有锁定状态，工作表有保护开关，区间可以挂数据校验，公式可以自动重算。这让“限填”这件事不用绕到业务层硬编码，而是在表格引擎内部就完成了约束。系统里其他地方只需要关心“数据从哪里来、填完后送到哪里去”。

1.3 和同类开源方案放在一起看

做在线表格选型，目前常见的路线还有SheetJS、Luckysheet、Handsontable、Grist、OnlyOffice这些。SheetJS偏文件解析和导出，Luckysheet的计算能力相对弱，Grist把表格做成了类数据库后台，适合重度管理系统；OnlyOffice功能全，但集成起来非常重。univer给我的感觉更接近一个“现代前端组件”：模块化、TypeScript生态、UI层可替换，数据、渲染、协作三个层面分离。对做业务系统的人来说，最实在的一点是它定位是“引擎”而不是“应用”，你可以把填报模板直接嵌进自己的系统里，而不是去适配一套完整的办公套件。

2. 设计思路：如何做到“可填写但不可修改”

2.1 从Excel继承来的“锁定+保护”机制

Univer在权限约束上沿袭了Excel的思路：每个单元格默认是“锁定”状态，但工作表保护默认是关闭的。锁定属性就像一把把锁，工作表保护才是决定“锁是否上到柜门上”的总闸。两者要同时生效，才能达到“指定区域不可编辑”的效果。

所以实现“指定单元格可填”，本质上只需要三步。第一步，把允许用户编辑的单元格标记为“未锁定（locked: false）”；第二步，其余单元格保持默认锁定；第三步，打开工作表保护。这样用户点进表格时，可编辑单元格能正常输入，锁定区域则无法进入编辑状态。这个设计与Excel用户的心智模型完全一致，业务方理解起来零成本，而且一个额外的好处是“保护”结果天然可迁移——如果用univer打开一份Excel文件，Excel里设置过的保护状态和锁定状态在拿到Univer里后也能继续复用，对存量业务导入很友好。

2.2 三种“填写区”设计模式

我在实际项目里总结下来，受限表格通常跑不出三种模式。

第一种是模板表模式。表头、说明行、公式列锁定，数据行开放。这是最常见的场景，像报价单、问卷登记、采购明细。操作上就是在模板初始化后，把整个填写数据区统一设置成未锁定，然后打开保护即可。

第二种是台账模式。历史数据锁定，新增行开放。这个适用于“老数据不能改，新数据随便加”的场景，比如工时记录、库存台账。难点在于需要动态维护锁定范围：每当用户新增行，新行默认是可编辑状态；而老数据区行要随着状态流转（比如“已提交”“已审批”）锁定。实现思路不复杂，根据业务状态把对应range重新设为locked之后刷新保护即可。

第三种是角色分区模式。同一张表里划出A列到C列给销售填，D列到F列给财务填，每列对应用户或角色组开放。这个在Univer里可以通过给不同range设置不同的锁定属性来实现，但要做得严谨，通常需要后端在初始化表格时，根据当前登录用户返回“哪些单元格可编辑”的配置，前端再按配置去设置锁定状态。锁定本身是表格层的“物理约束”，角色权限分配是业务层的“逻辑约束”，两者配合才能安全落地。

2.3 “软约束”同样重要：数据验证与条件格式

锁定解决的是“用户改不了”，但解决不了“用户填错”。这时候要靠数据验证：给填写区挂一个下拉枚举、限定数字范围、限制日期格式、控制最大长度。Univer支持数据验证能力，我通常会在姓名、电话、状态这类字段上都挂上校验，避免脏数据进入后端。有一点必须提醒：数据验证只是软约束，复制粘贴和外部导入是有可能绕过它的，所以关键字段在服务端必须再做一次兜底校验，前端表格里的数据验证更多是提升填写体验、降低人工出错率。

2.4 为什么Univer用Canvas绘图

第一次接触Univer的人都会好奇，为什么不直接用DOM表格。答案很简单：性能。Univer的表格主体是用Canvas绘制的，交互层用DOM来做框选、编辑框、滚动条这些附属物。Canvas在滚动和重绘时性能优势明显，实测几十万行数据拖动依然顺滑，而纯DOM表格到这个量级基本已经卡得没法用。代价也很直接：不能像改普通HTML那样直接DevTools里查DOM改样式，调试成本会高一些。如果你只是拿来做简单的在线编辑，体感不明显；一旦要深度定制主题、做自定义组件，就需要切换成“数据模型驱动渲染”的思维。

3. 实操落地：用Univer搭建一张“可填写但受限”的表格

3.1 工程准备与依赖安装

下面按一个最精简的Vite + TypeScript项目来演示。Node环境建议Node 18以上，包管理器用npm即可。需要的核心依赖如下：

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

需要注意，Univer迭代速度比较快，不同版本的插件注册方式和API名称有差异，安装时以官方npm包的最新版本为准。下面代码里的用法是我当前使用的版本的写法，核心概念是一致的，版本升级时对着官方示例仓库微调即可。

3.2 初始化Univer实例并渲染容器

初始化Univer实例其实是一个“组装模块”的过程：Univer负责调度所有模块，Sheet模块负责表格的数据模型和渲染，UI模块负责工具栏、右键菜单、Formula Bar这些外围控件。代码如下：

import { Univer } from '@univerjs/core'; import { createSheetsModule } from '@univerjs/sheets'; import { createSheetsUIModule } from '@univerjs/sheets-ui'; const univer = new Univer({ locale: 'zhCN', container: document.getElementById('app'), plugins: [ createSheetsModule(), createSheetsUIModule() ] });

如果不需要公式功能，也可以不注册formula相关模块，按需加载本身就是Univer的设计目标之一。启动后页面里就会出现一个完整的工作表。

3.3 创建工作簿与表格模板内容

有了实例，接下来创建一张工作簿和工作表。我习惯把模板初始化做成一个配置驱动的方法，而不是在代码里一行行写死单元格内容，这样不同业务只需要换一套配置对象就能生成不同的表。先看手动方式的写法：

const workbook = univer.createBook({ name: '客户信息登记表' }); const sheet = workbook.createSheet('登记表', { rowCount: 30, colCount: 8 }); // 第一行写入表头 sheet.getRange(0, 0, 1, 8).setValue([ ['编号', '客户名称', '联系人', '联系电话', '所在城市', '意向等级', '登记日期', '备注'] ]); // 给表头行设置加粗和背景色 sheet.getRange(0, 0, 1, 8).setStyle({ fontWeight: 'bold', backgroundColor: '#F2F2F2' }); // 给编号列预置一组序列，也可以由后端数据写入 sheet.getRange(1, 0, 10, 1).setValue([ ['C001'], ['C002'], ['C003'], ['C004'], ['C005'], ['C006'], ['C007'], ['C008'], ['C009'], ['C010'] ]);

批量写入时要尽量用“范围接口”，而不是逐单元格写入，后者会频繁触发渲染层的重绘，影响初始化速度。这也是Univer使用中一个比较重要的习惯：能做批量操作就做批量操作。

3.4 锁定模板区、开放填写区，这是核心一步

模板内容写完后，钥匙就在这里了。先把可编辑区域标记为未锁定，然后打开工作表保护。完整代码大概是这样的：

// 第2行到第11行中，C到G列（联系人、联系电话、所在城市、意向等级、备注）开放填写 const editableRange = sheet.getRange(1, 2, 10, 5); editableRange.setStyle({ protection: { locked: false } }); // 注册日期列用公式自动生成，也应该防止被改动 sheet.getRange(1, 6, 10, 1).setFormula('TODAY()'); // 打开工作表保护，只有未锁定单元格能被编辑 sheet.protect({ password: '' });

这里有两个细节值得展开。第一，单元格的locked属性是默认存在的，Excel和Univer里默认值都是true，所以“锁定”并不是一个需要手动开启的开关，而是需要在开放区手动关掉的默认项。很多初学者的误区是把所有区域手动设置一遍locked，其实完全没必要。第二，protect调用后，锁定状态立刻生效。就算用户通过按键Delete、粘贴、拖拽填充等方式操作，它也会被表格引擎拦截。对于更精细的区域保护，Univer还有区域级保护能力，可以针对某个子区间加权限说明、设置密码，适合模板表中“不同区域归属不同负责人”的场景。

3.5 给填写区添加数据验证与条件格式

锁定之后，再加上数据验证。我通常会做两个动作：给“意向等级”设置下拉枚举，给“联系电话”限制长度和格式。

// 意向等级下拉：高/中/低，不允许为空 sheet.getRange(1, 5, 10, 1).setDataValidation({ type: 'list', formula1: '"高,中,低"', allowBlank: false }); // 联系电话：文本长度等于11位（示例规则，按业务调整） sheet.getRange(1, 3, 10, 1).setDataValidation({ type: 'textLength', operator: 'equal', formula1: '11', allowBlank: true });

条件格式的作用更多是“可视反馈”。比如意向等级为“高”的时候，整行高亮，这样业务人员一眼就能看到重点客户。Univer也支持条件格式，但需要注意它的配置项在版本间变动较大，用的时候查一下当版本文档最稳妥。我自己的习惯是条件格式在需要强视觉引导时才用，不要堆太多规则，否则表格编辑时的重绘压力会变大。

3.6 与后端交互：取数、回写、导出

表格装好后，最终还是要回到业务闭环里。填报者在前端填完数据，我们需要把数据取出来交给后端保存。Univer的整个表格数据在内存里是一套对象模型，从模型里把指定范围的值读取成二维数组并不复杂，然后再通过业务接口提交。导出Excel这一步，可以用Univer自己的导出能力，也可以配合SheetJS做“读Univer数据、写xlsx文件”的组合，两种方式我都试过，后者对样式细节的还原度会更可控一些。等后端再次下发数据时，按模板重新初始化表格，再把数据库里的值set进对应区域即可。关键是：模板初始化逻辑和业务数据回填逻辑要分开写，不然每次打开表格都把用户销毁重建，体验会很差。

4. 常见问题与排查技巧实录

4.1 “单元格还是能改”：十有八九是保护没开

这是我在社群里被问得最多的问题，也是新手最容易踩的坑。许多人设置了锁定区域，但忘了调用protect()，或者保护代码写在数据初始化之前，后续数据变化导致保护状态被覆盖。排查思路很简单：先用代码打印一下工作表的保护状态，确认保护是开启的；再确认目标单元格的locked属性到底是不是false。Univer的实际机制和Excel一致，锁定属性只有在保护开启时才生效，两者缺一不可。如果都正确但还能改，就检查是不是有别的代码在后面重新设置了整行整列的样式，覆盖了锁定属性。

4.2 开放区域出现“奇怪”的不可编辑状态

有时候明明设置了某个区域未锁定，打开保护后却发现它还是不能编辑。原因通常是锁定的设置方式和expectation不一致：比如你先对整个工作表范围设置了locked=false，然后把整个工作簿设置为 locked=true，这种大范围覆盖会把你之前开放的区域重新锁住。还有一种情况是，在同一个范围内使用了两种设置接口，后执行的覆盖了先执行的。建议在每个range的锁定配置上只走一条路径：要么全部用setStyle，要么全部用保护配置API，不要混用。

4.3 填写完后公式不重算

Univer支持公式，但公式重算的触发条件有时和我们直觉不太一样。尤其是当你通过API直接写入单元格值时，有些版本不会主动触发整表重算，需要手动调用计算服务刷新。这个问题往往只在“外部数据写入”时出现，用户手填触发的重算通常没问题。排查方法是打开公式栏看公式是否还在，确认引用范围是否正确。遇到过最多的情况是：公式写在锁定区，但用户新增行后，公式引用范围没有扩展，新行里的公式列显示为空。解决思路是在初始化模板时，给公式列预留足够的空行范围，或者监听新增行事件后重新写入公式。

4.4 大数据量表格卡顿的排查思路

前面说了Univer用Canvas渲染性能不错，但当表格本身数据量很大的时候，仍可能出现卡顿。我从实践中总结的排查顺序是这样：先看是否启动了不必要的模块，比如表格中根本用不到图表和透视表，就不要注册对应插件；再看是否在滚动或编辑的高频事件里做了复杂逻辑，比如scroll监听里发请求、做格式判断，这些都会拖慢；第三看是否使用了过多的条件格式规则，每个条件格式在重绘时都是成本，规则超过几十条就要考虑精简。最后还可以在初始化sheet时就把行数列数控制在合理范围，不要给一个1000行乘500列的画布，只为了展示前20行的数据。

4.5 多人协同编辑时的冲突与并发

Univer支持协同编辑能力，但它的协同能力是需要额外部署协作后端模块的，并不是本地轻量应用默认带的功能。如果系统真的需要多人同时填写，必须把协同后端纳入架构设计。我在实际使用中感受比较明显的一点是，单元格锁定在协同场景下会变成“软竞争”：如果两个用户同时编辑同一个未锁定单元格，最终以操作序列合并的结果为准，而且锁定区域仍然不能被修改。在协同模式下，限制单元格权限依然可行，但并发冲突的处理和网络延迟对锁状态的同步，需要服务端做统一管理。这个部分复杂度会明显上一个台阶，建议先拿单机模板验证业务流程，再逐步引入协同架构。

4.6 一张速查表帮你快速定位问题

我个人在这几轮选型和实测里最强烈的感受是：Univer不是那种“装上就能一键交付”的库，它需要你像打磨业务组件一样去管理模板、锁定、校验、公式这些状态。但这也正是它值钱的地方——一旦你把“可填写区域”和“只读区域”的边界通过这套数据模型固化下来，整个填报流程就变得非常可控，需求方再也不会因为一张表被改得乱七八糟而半夜找你。

最后再分享一个小技巧。我在项目里会把“模板定义”抽成一个配置对象，里面记录表头、行数、可写区域、校验规则、需要预置的公式。每来一个新业务，只需要改配置，不需要动代码。这个习惯让你在接后续同类需求时，基本可以做到当天开发、当天联调。Univer的上手曲线不算平缓，但它的能力边界很宽，值得投入时间把这套“模板配置化”的思路沉淀下来。