1. 为什么我会盯上Univer从一次表格权限需求说起前段时间接了个让我头疼的需求公司几十个部门要在线上填同一张预算收集表每个部门只能改自己那几行的指定列其他任何格子都不能动。同事甩过来一版Excel模板说做到网页上就行。我一听就知道麻烦来了——市面上能嵌入网页的表格组件不少但绝大多数要么只能展示、要么要钱、要么交互太弱真正能模拟Excel那套先锁定部分单元格再保护工作表心智的掰着指头数得过来。我在GitHub上翻了半天最终把一个叫univer的开源项目拉进了项目清单。这是一个完全基于TypeScript构建的在线表格/文档/演示文稿一体化引擎代码结构非常现代和传统那种把Excel功能抄一层皮的轮子完全是两个路子。更关键的是它从底层设计了命令系统和插件机制保护工作表、数据验证这类限制用户操作的能力不是后期打补丁而是架构里留有明确的位置。如果你也在做这类在线表格可控填报的需求这篇文章值得看完。我会把选型逻辑、Univer的核心设计、实现只能填指定单元格的完整路径以及我在实跑过程中踩到的几个坑都讲清楚。不管你是准备自己搭一套数据收集工具还是在评估要不要对现有系统里的表格模块动刀这些内容都能帮你省至少两三天调研时间。先说结论Univer对标的不是又一个Luckysheet而是一套真正的Office引擎——它未来要覆盖的不只是表格还有文档和幻灯片。但代价也很明显版本推进快、API变动频繁、社区示例不够多。我用它做完第一版之后的最大感受是值得用但别指望所有问题都能从文档里找到答案很多时候得自己读源码。2. 为什么用户只能改指定单元格这么难需求拆解与三条实现路径把需求翻译成技术语言之前先看看让用户填一部分单元格、其他格子动不了到底涉及哪几层能力。第一层是可读性。用户需要看到整张表能滚动、能选中、能复制只是不能改。这一层相对容易但有些实现光做表格展示就会丢掉选择和高亮交互体验很糟。第二层是可写性。系统必须精确控制哪些range可编辑、哪些range不可编辑。控制不是画个灰色蒙层那种假把式而是从事件层面拦住输入。比如键盘输入、粘贴、拖拽填充、批量填充这些入口全部要走同一套管控机制。第三层是有效性。能填的区域还得校验格式——填金额不能写中文、填百分比不能超范围。这就是数据验证Data Validation的活了。在Univer之前我调研过几条实现路径路径A给Excel模板加锁定交给前端只读展示。简单但用户没法提交数据也不适合做流程流转。路径B用成熟商业组件。功能全但预算高而且许可证和私有化部署的问题够扯皮一阵。路径C用开源组件做深度定制。Luckysheet和x-data-spreadsheet我都试过前者功能多但代码历史长、维护有点随缘后者的编辑能力太基础。Univer吸引我的恰恰是它在路径C里走出了不一样的设计所有用户的编辑操作都通过**Command命令**对象走一遍这个设计天然适合做拦截——校验——放行/拒绝的逻辑。后面我需要做操作审计时也会受益于此。回到需求本身。在实现方案设计阶段我把只允许改B2:E10这样的需求分成了三种落地模式模式适用场景实现核心缺点模板工作表保护固定结构的收集表、预算表工作簿/工作表保护 单元格锁定样式需要用户前后端同时维护模板结构数据验证公式联动填报内容本身还要做下拉选择或公式计算在可编辑区域上施加数据验证规则拦截的是非法值而不是非法位置命令拦截后端鉴权同一张表多人多角色且审计要求高在Command层按range和角色做权限判断需要自行实现规则和数据模型注意这三个模式不是互斥的。我实际做预算填报表的时候三者是叠加使用的工作簿保护挡住大范围操作单元格锁定精确到哪些range可写数据验证再保证填入的值合法。这种组合拳的思路我觉得才是用户定义表格并限制他人修改这类需求的正解。3. Univer的架构里藏着什么命令系统、插件与保护机制Univer这个词乍看陌生它的主要能力覆盖Sheet、Docs、Slide三种文档类型核心是Sheet。我第一次看它的目录结构时第一反应是这不像一个表格组件更像一个小型Office套件。它对开发者最友好的地方在于你不需要操作DOM或者Canvas事件来管理单元格而是操作Univer提供的业务对象比如Workbook、Worksheet、Range然后用命令来改变它们的状态。这句话决定了整篇文章的思路在Univer里限制编辑本质上是给一个状态机加一道防线而不是给输入框加监听器。3.1 命令系统所有修改都有迹可循Univer里几乎每个操作都对应一个Command。插入行是命令合并单元格是命令设置数据验证是命令开启工作表保护也是命令。你可以通过CommandService来执行命令、监听命令执行前后的事件甚至可以在命令执行前阻断它。这个设计对限制编辑意义重大。因为你可以做一个命令拦截器在用户执行任何会修改单元格值的命令之前先判断目标range是否在允许编辑的集合内不在就直接拒绝。这样就不怕用户绕过UI——比如他不用输入法直接粘贴、拖拽填充这些途径都会被统一切到命令层。我在做审计功能时就受益于此。每次用户改动单元格会在命令的历史记录里留下一条可追踪的记录我可以据此做数据快照对比。如果用的组件不支持命令模式这种能力要额外写一堆防穿透代码。3.2 保护工作表与单元格锁定来自Excel的老朋友用惯了Excel的人都知道要在Excel里实现只能填某些格子最标准的操作是全选整表设置单元格锁定然后把允许编辑的区域取消锁定最后在审阅里开启保护工作表。这样会弹出一个密码框别人能不能改、能不能选锁定区域、能不能插入行列都可以逐项配置。Univer继承了这套心智每个单元格的样式里有一个锁定位工作表上有一个保护开关开关打开后默认锁定单元格不可编辑同时会记录密码以及若干放行策略。这和Excel的差别在于Univer把它做成了一套可供编程调用的API而不是藏在界面菜单里。3.3 插件与预设不要被陌生名词吓住早期使用Univer需要手动引入十几个包比如univerjs/core、univerjs/sheets、univerjs/sheets-ui、univerjs/sheets-formula等。后来官方提供了预设包一个UniverPresetSheet就能把前端编辑、工具栏、快捷键等能力打包拉起。我实际项目里用的是ReactVite直接通过npm安装了预设包再调用new Univer({ locale: ... })创建实例就得到一个完整的在线表格界面。初学阶段不必把所有包都理解透只记住几个关键概念即可Univer实例整个应用的总管理器。Workbook工作簿一个文件包含若干Sheet。Worksheet工作表具体那张网格表。Range区域比如A1:C10几乎所有操作都围绕Range展开。CommandService执行和监听命令的服务做拦截时主要用它。SheetProtection工作表保护对象控制锁定的行为与密码。有了这张地图后面写代码时就不会迷路。4. 实操从零搭建一个只有指定单元格可编辑的在线表格这节是全文的核心我直接把当时在项目里跑通的步骤铺开来讲。环境是这样前端用Vite React TypeScriptUniver的相关包锁定在当时的稳定版本线。如果你跟着做建议先搭一个最小Vite项目再逐步加Univer。4.1 安装依赖与创建容器先把Univer的几个核心包装进项目。以我当时的依赖为例npm install univerjs/core univerjs/presets univerjs/sheets univerjs/sheets-ui univerjs/sheets-formula univerjs/design univerjs/ui注意Univer版本更新比较频繁不同版本之间的包名和API会有调整我的示例基于9.x系列拿到新版本后如果提示找不到某个类或方法优先去看仓库里的examples目录那里通常有最新的写法。然后准备一个占满屏幕的容器// App.tsx import { useEffect, useRef } from react; import { LocaleType } from univerjs/core; import { Univer, UniverPresetSheet, UniverSheet } from univerjs/presets; export default function App() { const containerRef useRefHTMLDivElement(null); useEffect(() { if (!containerRef.current) return; // 1. 初始化 Univer 实例 const univer new Univer({ locale: LocaleType.ZH_CN }); // 2. 创建一张电子表格 univer.createUniverSheet( new UniverPresetSheet({ container: containerRef.current, toolbar: true, }) ); // 后面补上数据模板、锁定、保护的逻辑 }, []); return div ref{containerRef} style{{ width: 100%, height: 600px }} /; };这样跑起来页面上会出现一个带工具栏的空白表格。先别急着写业务确认Univer能正常渲染再往后走。4.2 把表格内容模板定义好要控制哪些单元格能改前提是表格本身的结构是确定的。我的做法是预先定义一个模板数据交给Univer渲染。以预算收集表为例A列是部门B列是预算项C列是金额D列是说明。市场部有3条预算项但每个部门只能填写自己那一段的C、D列。写代码时我通过初始化数据塞入了一个简单模板const sheetData { sheets: { budget: { name: 预算填报, rowCount: 30, colCount: 10, cellData: { 0: { 0: { v: 部门 }, 1: { v: 预算项 }, 2: { v: 金额 }, 3: { v: 说明 } }, 1: { 0: { v: 市场部 }, 1: { v: 差旅费 } }, 2: { 0: { v: 市场部 }, 1: { v: 活动物料 } }, 3: { 0: { v: 市场部 }, 1: { v: 投放费用 } }, 4: { 0: { v: 研发部 }, 1: { v: 服务器资源 } }, // 更多预算项…… }, // 也可以用 worksheetData 等方式设置样式和列宽 } } };这里强调一点先定义模板结构再谈锁定和权限。如果模板本身还在变化锁定规则很容易被需求推翻后面改起来心态会崩。4.3 设置单元格锁定与解除锁定Univer的单元格样式里有锁定位。按照Excel的玩法我要先给整张表默认锁定再把允许用户编辑的range解除锁定。实际操作中如果模板数据已渲染好我可以逐单元格读取再修改样式更省事的做法是直接读取当前Sheet实例批量设置样式。伪代码思路是这样的// 获取当前工作簿和工作表 const workbook univer.getUniverSheetInstance(univer.getActiveUniverSheet()?.getUnitId()); const worksheet workbook?.getActiveSheet(); // 遍历需要的区域设置 locked 状态 // locked true表示打开工作表保护后不可编辑 const lockRange ({ sheet, startRow, startCol, endRow, endCol, locked }) { sheet.getRange(startRow, startCol, endRow - startRow 1, endCol - startCol 1).setStyle({ locked }); }; // 1. 先全表锁定A1 到 最大范围 lockRange({ sheet: worksheet, startRow: 0, startCol: 0, endRow: 29, endCol: 9, locked: true }); // 2. 解锁允许填写的区域比如 C2:D3 市场部可填写区 lockRange({ sheet: worksheet, startRow: 1, startCol: 2, endRow: 3, endCol: 3, locked: false });这段代码没有完全照抄Univer的API因为我当时用的Range方法的名称在不同版本里也变过几次。如果你的版本里没有setStyle就打开控制台在worksheet实例上直接看它的方法列表通常有setRangeValues、setStyle或setRangeStyle之类的入口。读实例方法的习惯比死记API更重要。4.4 开启工作表保护光有锁定样式还不够必须开启工作表保护让锁定状态真正生效。这里的关键命令是SetWorksheetProtectionCommand之类的命令命令ID以版本为准。开启后所有被锁定的单元格都会拒绝用户的编辑操作而被解锁的区域可以正常填写。我的实现参考const protection { lock: true, password: 这里是可选密码, selectLockedCells: false, // 是否允许用户选中被锁定单元格 selectUnlockedCells: true, // 是否允许用户选中可编辑单元格 allowSelectLockedCells: false, allowSelectUnlockedCells: true, // 如果要严格控制可设置不允许插入行列、不允许删除行列 allowInsertRows: false, allowDeleteRows: false, }; await commandService.executeCommand({ id: sheet.command.set-worksheet-protection, params: { unitId: workbook?.getUnitId(), subUnitId: worksheet?.getSheetId(), protection, }, });执行完这段刷新页面马上会感觉到不一样整张表虽然看着是普通的表但只要点到锁定的单元格Univer的编辑交互会被拒掉而填写区可以随意输入。这里有个很重要的细节保护工作表开启后用户还是能选中和复制单元格内容只是不能改。对收集类场景来说这个体验基本是对的——允许查看、允许选取、拒绝写入。如果你连选中都想限制那要把selectLockedCells这类参数调成false但建议慎用限制太多会引起使用者的反感。4.5 加一层数据验证保证填的值合法单元格锁定了能填哪里数据验证负责填的什么值合法。我在这张预算表上用了一个简单规则C列金额必须是0到100万之间的数字。const dataValidationRule { type: number, operator: between, formula1: 0, formula2: 1000000, allowBlank: true, showInputMessage: true, promptTitle: 金额校验, prompt: 请输入0到100万之间的数字, showErrorMessage: true, errorTitle: 金额超范围, error: 金额必须在0到100万之间, };把这个规则绑到允许编辑的C2:D3区域上后用户即使能填填了超范围的值也会被即时拦截。下拉列表、日期范围、自定义公式都可以做成类似的规则。5. 我实际踩过的坑锁定与保护相关的四段排查实录纸上谈兵的部分讲完了这节是真正让我觉得Univer还年轻的部分。几乎每个坑排查的时候都能从源码里翻出答案但官方文档往往只字不提。我挑了四个最有代表性的按我当时的排查过程还原。5.1 坑一开启保护后连程序写入也被挡住了现象是我把申请表模板初始化好之后自己往C列预填了几个默认值结果页面加载完这几个值死活显示不出来。排查了一会儿发现不是数据没写进去而是我已经在上一行代码里就开启了工作表保护后续用命令写入被保护单元格的操作会被一并拦截。而在Excel里即便是保护状态VBA/脚本写入通常不受影响。Univer的命令系统则是一视同仁——保护机制工作在命令层不管是人点的还是代码发的只要目标是锁定单元格都会被拒绝。这个坑没造成业务问题但排查思路值得记录你得先设数据、设置好解锁区域最后再开保护。顺序反了不光用户写不进你自己也写不进。修复很简单把开启保护挪到所有初始化数据写入之后执行。我后来干脆封装了一个sheetReady异步任务按模板渲染 - 填充默认值 - 设置锁定样式 - 设置数据验证 - 开启保护 - 通知UI的顺序跑避免再出错。5.2 坑二设置了locked样式保护开了却不生效这个是让我最头痛的一个。前几步都照着做了单元格样式里也确认了locked: true但切换到页面后锁定单元格照样可以输入。我一度怀疑是不是Univer的锁定性子有问题。排错排了很久才找到根因样式设置的对象没有走命令系统或者命令没有真正找到目标sheet实例。我传入的sheetId写错了导致设置样式的命令在某张匿名表上执行而用户看到的那张表没被锁。检查方法很简单在浏览器控制台打印出所有workbook实例和sheet的ID和我代码里传的id比对一查一个准。另一个可能的原因是你需要用workbook.getActiveSheet()在页面加载完成后再获取Sheet如果在创建实例的同一个同步代码块里直接拿拿到的是尚未激活的表。我在代码里加了延迟或者用setTimeout后才稳定。5.3 坑三下拉列表会在保护模式下失灵我在D列说明加了一个数据验证下拉选项想让用户从预设的文案里选。保护开启后这个下拉箭头点击后居然弹不出来。一开始以为是数据验证和保护的冲突后来查了源码和示例才知道下拉选择本质上也是编辑操作如果触发下拉的那些单元格被锁定了交互会被保护逻辑提前拦截。解决办法有两个二选一把带下拉的单元格也设为locked: false然后对区域只应用数据验证而不依赖保护来限制或者保持锁定状态不要用下拉这种验证形式改用输入提示。我在预算表里选择了第一种把需要下拉的区域解锁其他区域保持锁定。数据验证本身已经能限制值下拉功能也就正常了。这个坑让我意识到一个原则锁定功能和数据验证功能是两套独立的系统叠加使用时必须清楚每套系统分别拦截的是位置还是值。如果你把二者混为一谈出了问题很难定位。5.4 坑四用户拖拽填充竟然能填进锁定区域用户反馈了一个诡异操作在可编辑单元格里输入数字后往下拖拽填充内容居然能覆盖到下方的锁定单元格。保护机制没有拦住拖拽填充。这个我倒是很快理解了。Univer里的拖拽填充和普通的setValue走的是不同的命令链在某些版本里填充操作对锁定状态的检查不完整。这属于开源组件在边界功能上的疏漏不是我没有配置正确。虽然这个行为不一定是Bug但对我的业务场景来说是不可接受的。我的处理方式是在命令层加了一个拦截器——这也是依赖命令系统的好处commandService.beforeCommandExecuted((command) { // 判断命令是否属于修改单元格内容的类型 if (command.id sheet.command.set-range-values) { const { range, rangeType } command.params ?? {}; // 检查range是否与允许编辑区域匹配 if (!isAllowedRange(range)) { return false; // 阻断该命令 } } });用这层拦截后不管用户是从输入法敲进来的、粘贴进来的、还是拖拽填充来的只要目标range不在白名单内统统被拒。这个兜底策略我强烈建议加纯靠组件的内置保护在边界操作上还是会漏。6. 三种落地模式怎么选给不同场景的配置建议上面讲了怎么用一个实例实现让用户填指定单元格但实际项目里这个需求往往不是单独一个页面而是一套流程的环节。我把三种典型的落地模式整理成一个对照方便你按自己情况判断。需求特征推荐模式配置要点备注固定模板、填完就交模板工作表保护全表锁定只放行填报区开启保护时不允许插入行列最省事适合预算、问卷需要下拉、日期、级联选择数据验证解锁下拉区域可编辑区解锁数据验证按列配置注意下拉的问题见5.3多角色、多口径、需要审计命令拦截后端鉴权实现beforeCommandExecuted转发后端权限判断最灵活也最费工夫举个例子如果你只在内部做个报销表收集模式A完全够用一个前端页面加一个提交按钮就落地了。但如果你做的是对外收集的订单登记表各部门人员权限还不一样那就必须上模式C——命令拦截层配合后端返回的权限规则才能在同一个模板上做到相同范围不同角色的精细化控制。我在预算表项目里采用的就是模式A模式的叠加保护机制主防命令拦截兜底。有一个原则始终不变凡是用户能看到的东西后台都要再做一遍权限判断。前端锁定只是体验优化不是安全机制。7. 再次谈选型心得什么时候用Univer什么时候绕开它用了Univer做了几个功能后我把它放到心里的嵌套组件库里每次新项目选型都会拿出来掂量掂量。总结一下我个人的判断希望能给你提供参考。适合用Univer的情况需要在线编辑表格且交互要尽量向Excel靠拢。有一些非表格软件但需要表格能力的场景比如把表格嵌进CRM工单、内容管理后台。未来还打算做在线文档或演示文稿想让技术栈复用同一套架构。团队里有能读TS源码的人不排斥在搜不到文档时自己去翻代码定位问题。要谨慎的情况只做纯展示、不需要编辑那直接用轻量渲染方案Univer有点大材小用。业务对版本稳定性极度敏感不接受API变动那要在发布前把版本锁死并保留排期做升级。需要表格里极其冷门的能力比如复杂的多区域打印专属定制建议先查一下issue里是否有人提过。当时选择trước这个方案前我也对比过努里的其它开源库最后打动我的还是那句朴素的话它是少数把在线表格当成核心产品而不是附带功能的项目。指定单元格可编辑、其他单元格不可修改这类需求在Univer的架构里有清晰的实现路径而不是靠外围hack。最后分享一点个人体会用这类年轻开源项目最大的敌人不是功能缺失而是你以为它和你熟悉的组件一样。实际上Univer的角色更接近一个框架你要把它当成业务系统的一部分去设计而不是当现成的表格插件。理解命令、保护、数据验证这三者的边界比抄一段示例代码重要得多。把基础概念吃透之后剩下的就是和版本打交道的事了。