最近在群里被问得最多的一个词是 Univer尤其是“在线表格能不能做成可填写的表单用户只能填某些格子其余格子动不了”。这个需求我在实际项目里做过不止一次而且每次做都要面对同一个问题很多现成的在线表格组件让你展示数据很容易让你精确控制“哪个单元格能编辑、哪个单元格只能看”却很吃力。Univer 是这两年开源社区里比较完整的在线表格/文档引擎底层是 TypeScript自带 Canvas 渲染、公式引擎、撤销重做和插件机制正好适合来承载这种带权限语义的表格场景。这篇文章我不打算重复官方文档而是从“如何用 Univer 实现用户定义表格 单元格锁定”这条主线出发把一个可落地的方案完整拆开。这里先给个定位Univer 适合谁如果你是前端工程师、全栈开发或者产品经理正在选型在线表格内核想做数据填报、报价单、审批表这类产品Univer 值得认真看。它跟传统的 iframe 嵌入 Excel 方案不一样Univer 是纯前端的可编程表格公式、格式、合并单元格、冻结行列、协同编辑都能通过 API 操作也就是说你的交互逻辑可以完全掌控。接下来我会先讲清楚它的设计逻辑再做一套完整的“可编辑区域控制”实现最后把我在上线过程中踩过的坑列出来。1. Univer 是什么在线表格里的可复用地基1.1 它不是 Excel 套壳而是一个可以自己装修的“地基”很多人在第一次接触 Univer 时习惯性把它理解成“网页版 Excel”。这个理解不算错但会在做技术选型时产生偏差。Univer 的核心不是把 Excel 搬到浏览器里而是提供一整套文档引擎工作簿、工作表、单元格、格式、公式、富文本这些数据模型都由自己管理界面渲染用的是 Canvas配合虚拟滚动来保证大表格的流畅度。你可以把它看成一块已经通电的毛坯房水电管线是通的墙也砌好了但每个房间里挂什么画、哪个房间对外开放完全由你决定。这种设计带来一个很实际的收益你能干预数据写入链路。在传统的嵌入式表格方案里用户点一个单元格开始打字这个行为通常直接落到组件内部你想在中间插一道“校验”很难或者只能靠后置校验等用户填错了再提示。而 Univer 里所有写操作都会走命令系统像“修改单元格”“插入行”“删除列”都是一个个命令命令在真正执行前会被命令服务分发你可以在这一层做拦截、修改、放行。这也就是后续实现单元格权限的突破口。1.2 Univer 的核心模块按需取用Univer 的能力是模块化的官方推的工程化方式是用 preset 组合核心包管数据模型和命令系统UI 包管工具栏、右键菜单和弹层公式包管计算协同包管多人实时编辑。对普通业务系统来说不一定要全量引入按需加载反而更可控。下面这个表是我常用的模块对照方便你第一次选品时有概念能力对应包/模块说明核心数据模型univerjs/core工作簿、工作表、单元格、命令服务表格渲染与 UIuniverjs/sheets、univerjs/preset-sheets画布渲染、选区、工具栏、右键菜单公式引擎univerjs/engine-formula计算链、跨表引用、自定义函数协同编辑官方协同包多人操作同步与冲突处理导入导出官方导入导出模块支持 xlsx 等常见格式版本之间 API 名称差异较大这是 Univer 目前最容易踩的坑之一。官方现在已经建议新项目直接基于 preset 初始化不再手动清单式地拼装插件。我自己的习惯是能按 preset 写的就不手写手写的部分尽量抽象成独立模块不要跟页面业务代码搅在一起。2. 需求拆解用户定义表格和“只能填特定单元格”2.1 这类需求的真实业务场景先说清楚“用户定义表格然后让用户填写一些单元格其他单元格用户无法修改”到底在解决什么问题。我见过最典型的场景是问卷调查和业务表单运营团队在后台先用表格拖出一份模板把“姓名”“电话”“城市”这些格子标记为可编辑其他所有格子都是只读说明业务人员拿到这条链接只能在白名单格子里输入连格式都不能动。这种体验比传统 HTML 表单要友好很多因为它保留了表格的表达能力比如合并单元格、批注、公示色块同时仍然具备表单的约束力。另一个常见场景是报价单和审批流。销售做报价时商品单价、折扣比例是只能看不能改的只有“数量”“备注”能编辑审批人在中间填“同意/不同意”其余区域全部锁定。如果没有单元格级权限你就只能拆成两个页面先展示数据再用普通输入框填审批意见。这样流程是通的但数据语义被切碎了后续对账、导出、改动历史都要自己做额外映射。Univer 能把“表格即界面表格即数据”这两件事合到一处。2.2 为什么不能靠“给表格盖一层遮罩”解决不少第一次做这个需求的朋友会先想到一个偷懒方案表格正常渲染再弹一层透明蒙层遮住不需要编辑的单元格用户点击被蒙层盖住的地方事件就不往下传。这个方案在演示 Demo 里看着能用一上线就露馅。首先单元格滚动和缩放之后蒙层坐标很难与表格画布严格对齐其次用户仍然可以通过键盘的 Tab 切换、CtrlV 粘贴、右键菜单的“清除内容”来绕过点击隔离最后你无法感知锁定状态背后的数据语义导出的文件也不会有任何权限标记。正确做法是把“是否能写”的规则放到数据层和命令层。数据层负责记录每个单元格的权限标记命令层负责在执行每一个写操作前校验该标记。这样不管用户是通过输入框打字、粘贴、拖拽填充还是菜单操作只要最终都会触发一个写命令就能被统一拦截。2.3 权限模型怎么设计才不给自己挖坑我建议至少设计成三张概念表模板表、实例表、单元格权限表。模板表存“这个表格长什么样”包括表头、背景色、校验规则实例表存“某一条填报记录”对应一行业务数据单元格权限表存“在某个模板里哪些格子可写”。用这个模型后台管理员配置的是一次模板每个用户可以分别在该模板下创建自己的实例互不影响。单元格锁定的规则表达式建议用 A1 或 R1C1 的区间来表示比如A2:C10、F5方便和导入导出工具对齐。这里有个容易忽略的细节权限不只是“能不能写”还包括“能不能选中”“能不能看到公式”。业务要求里如果只提了“不可修改”我至少会把“不可编辑”和“不可选中”分开处理。不可编辑指的是修改命令会被拒绝不可选中是交互层面的问题某些场景下也希望锁定单元格不能被点击选中从而避免用户误触。这两个不是同一个开关实现时要用不同的拦截点。3. 核心实现搭建 Univer 在线表格并让指定单元格可编辑3.1 初始化一个最简 Univer 工程先不引入任何复杂的插件只搭一个能看、能点、能输入的最小表格。现在官方文档推荐用统一 preset大致初始化代码如下import { Univer } from univerjs/core; import { UniverSheetsUIPreset } from univerjs/preset-sheets; const univer new Univer({ theme: default, presets: [ UniverSheetsUIPreset({ container: document.getElementById(app)!, }), ], });这段代码执行后页面上会出现一个完整的表格界面包含工具栏和选区。不同版本之间初始化参数可能有一些差异如果你用的是旧版仍然可以手动组合插件。我建议新人直接把官方文档的“快速开始”完整跑通一次然后再回到业务代码。实际项目里我不喜欢把初始化写死在组件内部更推荐封装成一个createSheetEngine(container, options)函数返回 Univer 实例和 API 入口这样后面接入权限、协同、路由切换都比较清晰。3.2 拿到 Univer 的编程 API操作单元格初始化完成之后通常可以用univer.getAPI()拿到高层 API。通过高层 API 操作活动工作簿是最不容易出错的方式比如先取工作表再取单元格区间再写值const api univer.getAPI(); const workbook api.getActiveWorkbook(); const sheet workbook.getActiveSheet(); // 读取单元格 const value sheet.getRange(0, 0).getValue(); // 写入单元格 sheet.getRange(0, 0).setValue(Hello);这里的行列索引是 0 起始的和界面里显示的第一行第一列对应。需要注意setValue本身也是一个命令它会走命令服务。也就是说即便你后来在 UI 上锁定了单元格只要某个入口误调用这些 API数据一样会被改。所以真正完整的权限控制必须做在底层命令拦截而不是只做在按钮隐藏上。这也是我后面建议接入命令层校验的原因。3.3 定义可编辑区域用一张内存表管住所有白名单我常用的做法是维护一个权限模块核心就是一个可编辑区域集合支持精确单元格或区间type CellRef { row: number; col: number }; class EditZoneManager { private editable new Setstring(); add(row: number, col: number) { this.editable.add(${row}:${col}); } addRange(sheet, startRow, startCol, endRow, endCol) { for (let r startRow; r endRow; r) { for (let c startCol; c endCol; c) { this.editable.add(${r}:${c}); } } } canEdit(row: number, col: number): boolean { return this.editable.has(${row}:${col}); } }这里的 key 用row:col只是为了逻辑清晰线上项目建议直接用一个二维坐标转一维索引的函数或者用位运算组合数据量大了以后查找更快。小项目用 Set 就够几十万单元格规模也可以接受。注意这只是前端的内存表真正的权限判定在后端接口里还要再做一遍前端规则只是改善体验的。3.4 拦截写命令无论键盘、粘贴还是 API 都无法绕过权限判定的关键点在命令服务。Univer 执行“修改单元格值”这类操作时会先发出对应的命令命令里带着要修改的范围和值。我们可以在命令真正执行前挂一个拦截器解析命令携带的单元格坐标逐个判断是否为白名单import { SetRangeValuesCommand } from univerjs/sheets; const guard univerAPI.getCommandService().beforeCommandExecuted((command) { if (command.id ! SetRangeValuesCommand.id) { return; } const params command.params; // params 里通常包含 sheetId、range 信息、value 信息 const { ranges, value } params; if (!ranges || !ranges.length) return; for (const range of ranges) { for (let r range.startRow; r range.endRow; r) { for (let c range.startColumn; c range.endColumn; c) { if (!editZoneManager.canEdit(r, c)) { // 阻止写入并提示用户 // 不同版本可以通过返回值 false 或抛出中断异常来取消命令 return false; } } } } });上面这段代码里的命令 ID 和参数结构不同版本会有细节差别具体的要以你安装包的SetRangeValuesCommand定义为准。核心思路是通用的把命令层当作唯一入口对写入类命令做白名单校验。拦截器返回 false 或抛出异常后界面上的单元格不会发生任何变化用户能感知到“这格打不了字”但程序不会崩溃。3.5 让锁定从“看得见”变成“摸不着”视觉和交互一起锁光拦截命令还不够用户体验上必须让用户一眼看出哪些格子能填、哪些格子是死的。第一件事是给可编辑单元格一个明显的底色比如白底加浅色边框锁定的单元格用灰底或者斜纹填充。这个可以直接在初始化表格时用样式接口设置也可以在权限模块变更后统一刷新。第二件事是禁用右键菜单中针对锁定区域的“清除内容”“插入”“删除”等操作否则用户会用一个原本合法的命令来曲线绕过。还可以做一个“填写模式”开关进入填写模式后锁定单元格默认不可选中点击锁定区域时Univer 的选区会被强制跳回最近的一个可编辑单元格。这个交互在移动端尤其重要避免用户手指点到错误区域后弹出生涩的选区动画。这里的关键是监听选区变化事件再去判断选区是否落在非编辑区内如果是就重置选区。听上去简单实际做的时候要注意别和用户的正常拖拽选择冲突一般只重置点击产生的选区不重置拖拽产生的选区。3.6 把权限配置做成可视化让运营自己定义可填格如果要做到标题里说的“支持用户定义表格”那配置端最好也别写死在代码里。我通常会做一个“配置模式”运营点右下角切换按钮进入配置模式然后用鼠标直接圈选一片区域弹出的面板里点一下“允许填写”后台就把这个区域写进模板的权限 JSON 里。Univer 的选区事件天然支持这种交互做起来比传统表单拖拽设计器还要顺。配置模式里的核心逻辑是用户圈选区域后把选区转成标准的startRow、startColumn、endRow、endColumn再转成权限 JSON 存到后端。发布模板后读取权限 JSON把可编辑区域导入到前端的 EditZoneManager同时给这些区域应用编辑样式。这个小闭环就是我们整个功能的主链路配置、发布、填写、回收数据。权限设置上尽量考虑区间合并不要把几千个单元格逐个拆开存否则后台要存储的数据量会涨得很快。4. 常见问题排查为什么明明锁了还是被改了4.1 撤销重做是第一个绕过后门很多朋友把拦截器写好之后很兴奋地点了一个锁定单元格发现输入内容确实没变于是以为万事大吉。结果用户按下 CtrlZ 撤销之前的操作锁定的单元格却跟着变了。原因很简单撤销重做也是一个命令它同样要经过命令服务但是命令 ID 不同。如果守卫只处理了“修改单元格值”这一类命令没有拦截“撤销”“重做”对应的命令那么用户通过撤销就能绕过锁定。排查思路是在拦截器里不要只判断一个命令 ID而要把范围扩大到一个“可写命令名单”。凡是最终会改变单元格数据、行高列宽、单元格样式、合并状态、行列结构的命令都应该纳入白名单校验。具体来说可以维护一个数组把这些命令的 ID 列出来初始化时注册进拦截器。后续如果发现还有别的新命令能绕过就在这个数组里补上。4.2 粘贴与拖拽填充会比普通输入多出大跨区粘贴是最容易漏掉的场景。用户可能从 Excel 复制了整块内容然后点到一个锁定单元格上按 CtrlV。粘贴命令产生的写入范围往往不是你肉眼看到的那个格子而是一个矩形选区。如果拦截逻辑只校验选区左上角的单元格后面一串锁定区域都会被悄悄写入。同理拖拽填充手柄也可以跨越只读区域把公式或数值复制过去。修法一致凡是要处理一个写入范围的命令必须遍历整个矩形区间的每个单元格不能只看起点。4.3 样式、合并和行列结构也是数据只读需求通常说的是“单元格的 value 不能改”但从业务上看用户也不应该能改锁定的背景色、字体、行高列宽或者把锁定的区域合并/拆分。如果权限模型只拦住 value 写入其他操作如SetRangeStyleCommand、InsertRowCommand、MergeCellCommand仍然会被放行。所以我在需求评审时都会跟产品确认一句话“不可修改”是仅仅指内容还是包括格式和结构按我的经验绝大多数业务要的是后者那就必须把这些命令全部纳入黑名单对照表。下面是一个常见命令匹配表方便排查时对着找用户操作可能触发的命令是否需要拦截输入文字SetRangeValuesCommand 等必须粘贴粘贴命令/SetRangeValues 组合必须拖拽填充填充命令必须撤销/重做UndoCommand/RedoCommand必须修改样式SetRangeStyleCommand 等按需求插入行/列InsertRowCommand/InsertColCommand按需求合并单元格MergeCellCommand按需求清除内容ClearRangeContentCommand必须4.4 协同编辑场景前端权限只是客户端体验后端才是底线Univer 在线协同能力非常强但协同会把权限问题放大。如果两个用户同时打开同一张表A 在前端被拦截不能写B 却通过直连 API 或另一个前端环境写入了一个锁定区域那么同步之后A 的界面里可能也会看到这个“本不该出现”的数据。所以我始终强调Univer 前端的权限破坏的是用户体验真正的数据安全要由服务端在接收每个协同操作时再做校验。协议层必须有白名单服务端不认识的写入操作直接拒绝。实际做协同避坑时我会把权限规则哈希一下下发到前端前端拦截失败时当作错误上报而不是当作正常业务数据落库。这样既能快速发现前端漏写的命令 ID也不会因为前端 bug 污染整张表。这个设计看起来简单但常被忽略。4.5 性能话题不要在全表范围做 O(n^2) 校验如果一次写入命令涉及几万行的大范围粘贴而权限集合又是一个巨大的 Set逐格判断会卡住主线程。解决思路是分段索引把权限区间按行号排序或者按列族分组判断时先做区间二分再做细粒度命中。绝大部分业务场景的可编辑区域都远小于总区域这种优化很容易带来明显收益。我个人的经验是表格类的性能问题不要在后期盲猜先用浏览器 Performance 面板抓一下命令执行耗时定位到具体卡顿的函数再优化。5. 扩展落地把 Univer 嵌入业务系统的重要细节5.1 接入 React/Vue 时的生命周期管理Univer 实例是典型的非 React 资源直接放在组件里创建React 严格模式或者热更新下可能会创建多个实例造成内存泄漏和界面叠加。我的做法是把它封装成一个useUniverSheet自定义 Hook内部处理创建和销毁组件卸载时调用univer.dispose()。Vue 侧道理一样把实例绑定在组件的onMounted和onBeforeUnmount生命周期上。这个坑虽然基础但我在几个项目里都帮同事擦过屁股值得单独记一笔。5.2 导入导出后的权限一致性用户模板如果允许导出 xlsx导出的文件是否要保留可编辑区域的标记这里有两个选择如果要求不高导出成普通 xlsx 就行导出的文件不再限制如果要求高建议把权限信息写到自定义单元格批注或者隐藏在某个扩展工作表里。导出时把锁定区域统一设置成 Excel 原生的“保护单元格”属性配合工作表保护密码是可以做到的但密码一旦泄露就形同虚设。所以导出权限保护只能作为辅助不能替代在线系统的权限校验。5.3 后续可以扩展的方向一套 Univer 单元格级权限的实现下一步自然会长出更多能力比如针对不同角色下发不同可编辑区域、根据单元格值做联动校验、把校验结果用数据条和图标集展示在表格里、把填报结果通过提交按钮回写后端。如果你正在做的是数据填报类 SaaS这套地基是够用的。核心并不是某一段代码而是“命令层拦截 数据层权限 服务端兜底”这套三角关系把这个模型想清楚Univer 的其他功能都能在这个骨架上往下长。最后说一点我自己的教训。我在做这类项目时被咬得最疼的一次是忘了处理撤销命令运营第二天跑来投诉说用户虽然填不了格子但可以先输入一点内容再 CtrlZ 把锁定的表头内容也带出来。那次之后我就形成了一个习惯每次新加一个能改数据的入口先看一眼命令清单再跑一次“锁定区域写入、粘贴、撤销、拖入填充、合并单元格”五连测做完再发版。这个小测试列表成本很低但能挡住绝大部分回归问题。希望这些踩坑经历能帮你少走几段弯路。