1. 从“univer”这个关键词说起它到底解决什么问题第一次看到“univer”这个词很多人会以为是某个新出的前端框架或者又一个在线表格工具。但如果你真正翻过它的文档、跑过它的 Demo就会发现它的定位比“在线 Excel”要底层得多——它是一套电子表格内核 可编程 SDK把“表格”这件事拆成了可复用的能力再通过 Facade API 暴露给上层业务。我最初接触它是因为一个很具体的需求客户要在后台管理系统里嵌入一个“预算填报”模块表格的模板由管理员定义普通员工只能填写指定单元格其余单元格锁死不可改。听起来简单但真做起来用传统方案要么是直接嵌一个第三方在线表格定制能力差、数据不好拿要么是自己用 Canvas 从零画工作量爆炸。univer 恰好卡在中间它给你一套完整的表格渲染和计算内核同时把“哪些单元格能编辑、哪些不能”这种业务规则交给你来控制。所以这篇内容不是泛泛地介绍“univer 是什么”而是围绕一个真实场景——用户定义表格模板其他人只能填写指定单元格——把 univer 的核心机制、Facade API 的用法、Canvas 渲染的注意点、以及 Node.js 环境下的工程化问题全部拆开讲清楚。适合两类人看一类是正在选型、想知道 univer 能不能扛住自己业务的前端或全栈工程师另一类是已经决定用 univer但被 Facade API 和权限控制绕晕的开发者。关键词里出现的 SDK、Node.js、Canvas、Facade API基本就是 univer 落地的四条主线。下面我按“先搞懂它怎么组织数据再搞懂它怎么控制权限最后搞懂它怎么跑起来”的顺序展开。2. univer 的数据模型为什么“锁定单元格”不是改个属性那么简单2.1 工作簿、工作表、单元格的三层结构univer 的数据组织方式和 Excel 很像但更“程序化”。一个Workbook工作簿下面挂多个Worksheet工作表每个工作表里是二维的Cell单元格矩阵。但真正决定一个单元格“长什么样、能不能改”的不是单元格本身而是挂在它上面的一堆配置对象。我一开始以为“锁定单元格”就是给 cell 加个locked: true结果发现完全不是。univer 把“样式”“权限”“数据验证”拆成了不同的模块每个模块有自己的配置入口。比如样式字体、颜色、边框走的是IStyleData权限能不能编辑走的是IPermissionData或者通过 Facade API 的setRangePermission之类的方法数据验证只能填数字、只能填日期走的是IDataValidation。这种拆分的好处是灵活坏处是新手容易找不到入口。我踩的第一个坑就是明明设置了单元格只读但用户还是能通过粘贴、拖拽填充的方式改掉它。后来才明白只读控制必须同时覆盖“直接编辑”“粘贴”“拖拽”“删除”这几条路径只堵一条路是没用的。2.2 模板定义与填写分离谁来决定哪些格子能改回到“用户定义表格其他人填写”这个场景。这里其实有两个角色模板设计者他打开一个设计界面画出表格结构指定哪些区域是“可填写区”哪些是“固定区”。填写者他打开同一个表格但只能动可填写区。在 univer 里这个分离不是靠“两个不同的表格文件”实现的而是靠同一份数据 不同的权限视图。模板设计者保存的是一份完整的 Workbook 快照包括所有单元格的值、样式、权限配置填写者加载这份快照后univer 会根据权限配置决定哪些单元格进入可编辑状态。这里有个关键点权限配置本身也是数据的一部分。也就是说你不需要在代码里硬编码“A1 到 C3 可编辑”而是让模板设计者通过界面操作把权限信息写进 Workbook 的配置里。填写者加载时univer 自动读取这些配置。我实际做的时候用了一个取巧但很稳的办法在模板设计阶段给所有“可填写单元格”打上一个自定义的元数据标记比如meta: { editable: true }然后在填写者加载时遍历所有单元格把没有这个标记的单元格统一设为只读。这样做的好处是模板设计者不需要理解 univer 的权限 API只需要在界面上点“标记为可填写”剩下的交给代码。2.3 为什么不用“隐藏 保护工作表”的老办法Excel 里有“保护工作表”功能可以锁定单元格。univer 也支持类似的能力但我不建议在“模板 填写”场景里直接用工作表级保护。原因有两个第一工作表级保护是“全有或全无”的粒度。你要么保护整个表要么不保护。虽然可以指定“允许用户编辑的区域”但那个区域是连续的矩形遇到“可填写单元格分散在不同行不同列”的情况就歇菜了。第二工作表级保护会连带影响很多交互行为。比如用户想调整列宽、想排序、想筛选都可能被一起禁掉。而业务上往往只希望“不能改值”其他操作照常。所以更合理的做法是单元格级权限控制配合 Facade API 在运行时动态判断。下面讲具体怎么落地。3. Facade API 实战把“只能填指定单元格”拆成可执行的代码3.1 Facade API 是什么为什么它比直接操作内核更靠谱univer 的内核Core是一套很底层的模块系统直接操作内核意味着你要理解Command、Mutation、Domain这些概念学习曲线很陡。Facade API 是官方提供的一层“门面”把常用操作封装成更直观的方法比如univerAPI.getActiveWorkbook()拿到当前工作簿worksheet.getRange(A1:C3).setValue(...)设置区域值worksheet.getRange(A1).getCellStyle()拿样式。我一开始图省事直接翻内核源码改 Mutation结果升级版本时全挂了。后来改用 Facade API虽然有些高级功能它还没暴露但稳定性好太多。对于“模板 填写”这种业务场景Facade API 基本够用实在不够再考虑自定义 Command。3.2 加载模板后如何批量设置只读假设模板设计者已经保存了一份 Workbook 快照里面用自定义元数据标记了可填写单元格。填写者加载后我们要做的是遍历所有单元格把没有标记的设为只读。Facade API 里没有直接的“遍历所有单元格”方法但可以通过getSheet()拿到工作表再用getRange()配合行列数来遍历。代码大概长这样const workbook univerAPI.getActiveWorkbook(); const worksheet workbook.getActiveSheet(); const rowCount worksheet.getMaxRows(); const colCount worksheet.getMaxColumns(); for (let r 0; r rowCount; r) { for (let c 0; c colCount; c) { const cell worksheet.getRange(r, c); const meta cell.getCellMeta(); // 假设有获取元数据的方法 if (!meta || !meta.editable) { cell.setLocked(true); // 伪代码实际 API 名称可能不同 } } }这里有个性能坑如果表格很大比如 1000 行 × 50 列双重循环会卡死。我的优化方案是只遍历有内容的区域用worksheet.getDataRange()拿到实际有数据的范围再在这个范围内遍历。另外设置只读的操作最好批量提交而不是逐个单元格调用否则会触发大量重渲染。3.3 拦截粘贴和拖拽只读控制的隐藏漏洞前面提到只设locked是不够的。用户可以通过 CtrlV 粘贴、拖拽填充柄、甚至删除行来绕过。univer 提供了事件拦截机制可以在这些操作发生前判断目标区域是否可编辑。以粘贴为例Facade API 里可以监听BeforeClipboardPaste之类的事件具体名称以文档为准在回调里检查粘贴目标区域是否包含只读单元格。如果包含就取消这次粘贴。univerAPI.onBeforeClipboardPaste((params) { const targetRange params.targetRange; if (containsLockedCell(targetRange)) { params.cancel true; // 阻止粘贴 // 可以在这里弹个提示 } });拖拽填充同理监听BeforeFill事件。删除行/列则监听BeforeDeleteRange。关键思路是所有会改变单元格值的操作都要过一遍权限检查。我一开始只拦了直接编辑结果测试时被用户用粘贴轻松绕过返工了一次。3.4 给可填写单元格加视觉提示光锁住还不够用户得知道“哪里能填”。univer 支持自定义单元格样式可以给可填写区域加个浅色背景或者边框。做法是在加载模板后遍历可填写单元格设置一个醒目的样式。但这里要注意样式和权限是两回事。你给单元格加了背景色不代表它就可编辑反过来可编辑的单元格也不一定非要加背景色。我见过有人把“可编辑”和“有背景色”绑死结果模板设计者想改个颜色把权限也改没了。正确的做法是两者独立配置只是视觉上保持一致。4. Canvas 渲染与 Node.js 工程化那些文档里不会写的坑4.1 Canvas 渲染的性能边界在哪里univer 的表格是用 Canvas 画的不是 DOM。这意味着它的性能上限比 DOM 表格高很多但也带来一些特殊问题。第一个问题是首屏渲染时间。如果表格很大Canvas 需要一次性画出所有可见区域初始化会慢。我的经验是超过 5000 个单元格的表格首屏加载要加 loading 状态否则用户会以为页面卡死。第二个问题是滚动时的重绘。univer 做了虚拟滚动只画可见区域但如果你在滚动事件里做了重计算比如动态权限判断就会掉帧。我的做法是权限判断只在加载时做一次结果缓存起来滚动时直接读缓存。第三个问题是导出和打印。Canvas 画出来的东西直接打印会糊。univer 提供了导出图片或 PDF 的能力但需要额外配置。如果业务有打印需求最好提前测试。4.2 Node.js 环境下的安装与版本选择univer 是前端库但它的构建和测试依赖 Node.js。关键词里出现了“node.js 22.12”说明新版本对 Node 有要求。我实测下来Node 18 LTS 也能跑但 Node 20 以上更稳因为一些构建工具链对旧版本支持不好。安装步骤没什么特别的但有两个坑第一不要用太老的 npm。univer 的依赖树里有几个包用了较新的 package.json 特性npm 6 会报错。建议 npm 9 以上。第二如果公司网络有代理记得配好 registry。这个不多说配不好连依赖都拉不下来。node -v # 确认版本 18 npm -v # 确认版本 9 npm install univerjs/core univerjs/facade4.3 和现有前端框架的集成方式univer 不绑定框架React、Vue、甚至原生 JS 都能用。但集成时有几个注意点容器尺寸univer 需要一个有明确宽高的容器否则 Canvas 画不出来。我见过有人把容器设成height: 100%但父元素没高度结果白屏。销毁时机组件卸载时要调用univer.dispose()否则会有内存泄漏。React 里放在useEffect的清理函数里。多实例一个页面里不要创建多个 univer 实例除非你确定需要。多个实例会争抢 Canvas 资源性能很差。5. 权限控制的边界与常见误判5.1 “只读”不等于“不可见”很多人把“锁定单元格”理解成“隐藏单元格”这是两码事。只读意味着用户能看到值但不能改隐藏意味着用户根本看不到。在预算填报场景里通常需要用户看到固定区的值比如科目名称、计算公式所以是只读而非隐藏。univer 支持隐藏行/列但那是另一个维度的控制。权限控制管的是“能不能改”隐藏控制管的是“能不能看”两者要分开设计。5.2 公式单元格的特殊处理如果固定区里有公式比如合计行用户虽然不能直接改但可能通过修改可填写区的值来间接影响公式结果。这是正常的也是业务需要的。但要注意公式的计算范围如果包含了只读单元格而只读单元格的值又被程序修改了公式会重新计算。这通常没问题但如果你的业务逻辑依赖“只读单元格的值绝对不变”就要小心。我的做法是在保存填写结果时只提取可填写单元格的值固定区的值以模板为准不信任前端传回来的固定区数据。这样即使前端被篡改后端也能保证数据一致性。5.3 多用户并发填写的冲突问题如果多个用户同时填写同一份模板univer 本身不提供协同能力协同需要额外的协同引擎。在“模板 填写”场景里通常是每个用户填自己的副本最后汇总。所以并发冲突不是大问题。但如果你要做“多人同时填一张表”那就需要引入协同层univer 有对应的协同方案但配置复杂度会上升一个量级。我的建议是如果业务允许尽量做成“每人一份副本”省掉很多麻烦。6. 从模板设计到数据回收的完整链路6.1 模板设计器的最小实现模板设计器不需要太复杂核心功能就三个画表格结构、标记可填写区、保存快照。univer 本身就是一个完整的表格编辑器你只需要在它的基础上加一个“标记”按钮。标记的逻辑可以很简单用户选中一个区域点“设为可填写”代码就给这个区域的每个单元格打上editable: true的元数据。保存时把整个 Workbook 序列化成 JSON 存到后端。6.2 填写页面的加载与提交填写页面加载时从后端拉取模板 JSON用 univer 加载然后执行权限设置把没有editable标记的单元格设为只读。用户填完后点提交代码遍历所有可填写单元格收集值发给后端。这里有个细节收集值时要用单元格的“显示值”还是“原始值”如果单元格有格式化比如日期、百分比显示值和原始值可能不一样。我的经验是存原始值展示时再格式化这样后端处理更方便。6.3 后端如何校验填写结果后端不能信任前端传来的数据。校验逻辑至少包括检查提交的单元格是否都在可填写区内检查值的类型是否符合模板定义比如数字字段不能传字符串检查必填项是否都填了。这些校验规则可以从模板 JSON 里提取不需要硬编码。我在项目里把校验规则也存进了模板的元数据里后端读取后动态校验模板改了校验规则也跟着变。7. 一些实测下来的经验与建议关于性能univer 的 Canvas 渲染在中等规模表格几千个单元格下非常流畅但如果你要做“全表遍历 逐单元格设置权限”一定要做范围限制和批量提交。我试过在 2000 行 × 30 列的表上逐单元格设只读卡了将近 10 秒改成只遍历数据区 批量提交后降到 1 秒以内。关于版本升级univer 还在快速迭代Facade API 偶尔会有破坏性变更。我的建议是锁定小版本号升级前先看 changelog别盲目追新。关于文档univer 的官方文档覆盖了核心概念但很多实战细节比如粘贴拦截、性能优化需要翻源码或社区讨论。遇到问题先搜 issue大概率有人踩过同样的坑。关于选型如果你的需求只是“展示一个只读表格”用普通 HTML 表格就够了没必要上 univer。但如果你需要“用户可编辑 精细权限控制 公式计算 大数据量”univer 是目前少有的能同时满足这几点的开源方案。最后分享一个我常用的调试技巧在开发阶段把 univer 的 Workbook 快照打印到控制台看看权限配置到底写进去了没有。很多时候问题不在代码逻辑而在配置根本没生效。这个习惯帮我省了不少排查时间。
Univer 电子表格内核实战：基于 Facade API 实现单元格级权限控制与模板填写
1. 从“univer”这个关键词说起它到底解决什么问题第一次看到“univer”这个词很多人会以为是某个新出的前端框架或者又一个在线表格工具。但如果你真正翻过它的文档、跑过它的 Demo就会发现它的定位比“在线 Excel”要底层得多——它是一套电子表格内核 可编程 SDK把“表格”这件事拆成了可复用的能力再通过 Facade API 暴露给上层业务。我最初接触它是因为一个很具体的需求客户要在后台管理系统里嵌入一个“预算填报”模块表格的模板由管理员定义普通员工只能填写指定单元格其余单元格锁死不可改。听起来简单但真做起来用传统方案要么是直接嵌一个第三方在线表格定制能力差、数据不好拿要么是自己用 Canvas 从零画工作量爆炸。univer 恰好卡在中间它给你一套完整的表格渲染和计算内核同时把“哪些单元格能编辑、哪些不能”这种业务规则交给你来控制。所以这篇内容不是泛泛地介绍“univer 是什么”而是围绕一个真实场景——用户定义表格模板其他人只能填写指定单元格——把 univer 的核心机制、Facade API 的用法、Canvas 渲染的注意点、以及 Node.js 环境下的工程化问题全部拆开讲清楚。适合两类人看一类是正在选型、想知道 univer 能不能扛住自己业务的前端或全栈工程师另一类是已经决定用 univer但被 Facade API 和权限控制绕晕的开发者。关键词里出现的 SDK、Node.js、Canvas、Facade API基本就是 univer 落地的四条主线。下面我按“先搞懂它怎么组织数据再搞懂它怎么控制权限最后搞懂它怎么跑起来”的顺序展开。2. univer 的数据模型为什么“锁定单元格”不是改个属性那么简单2.1 工作簿、工作表、单元格的三层结构univer 的数据组织方式和 Excel 很像但更“程序化”。一个Workbook工作簿下面挂多个Worksheet工作表每个工作表里是二维的Cell单元格矩阵。但真正决定一个单元格“长什么样、能不能改”的不是单元格本身而是挂在它上面的一堆配置对象。我一开始以为“锁定单元格”就是给 cell 加个locked: true结果发现完全不是。univer 把“样式”“权限”“数据验证”拆成了不同的模块每个模块有自己的配置入口。比如样式字体、颜色、边框走的是IStyleData权限能不能编辑走的是IPermissionData或者通过 Facade API 的setRangePermission之类的方法数据验证只能填数字、只能填日期走的是IDataValidation。这种拆分的好处是灵活坏处是新手容易找不到入口。我踩的第一个坑就是明明设置了单元格只读但用户还是能通过粘贴、拖拽填充的方式改掉它。后来才明白只读控制必须同时覆盖“直接编辑”“粘贴”“拖拽”“删除”这几条路径只堵一条路是没用的。2.2 模板定义与填写分离谁来决定哪些格子能改回到“用户定义表格其他人填写”这个场景。这里其实有两个角色模板设计者他打开一个设计界面画出表格结构指定哪些区域是“可填写区”哪些是“固定区”。填写者他打开同一个表格但只能动可填写区。在 univer 里这个分离不是靠“两个不同的表格文件”实现的而是靠同一份数据 不同的权限视图。模板设计者保存的是一份完整的 Workbook 快照包括所有单元格的值、样式、权限配置填写者加载这份快照后univer 会根据权限配置决定哪些单元格进入可编辑状态。这里有个关键点权限配置本身也是数据的一部分。也就是说你不需要在代码里硬编码“A1 到 C3 可编辑”而是让模板设计者通过界面操作把权限信息写进 Workbook 的配置里。填写者加载时univer 自动读取这些配置。我实际做的时候用了一个取巧但很稳的办法在模板设计阶段给所有“可填写单元格”打上一个自定义的元数据标记比如meta: { editable: true }然后在填写者加载时遍历所有单元格把没有这个标记的单元格统一设为只读。这样做的好处是模板设计者不需要理解 univer 的权限 API只需要在界面上点“标记为可填写”剩下的交给代码。2.3 为什么不用“隐藏 保护工作表”的老办法Excel 里有“保护工作表”功能可以锁定单元格。univer 也支持类似的能力但我不建议在“模板 填写”场景里直接用工作表级保护。原因有两个第一工作表级保护是“全有或全无”的粒度。你要么保护整个表要么不保护。虽然可以指定“允许用户编辑的区域”但那个区域是连续的矩形遇到“可填写单元格分散在不同行不同列”的情况就歇菜了。第二工作表级保护会连带影响很多交互行为。比如用户想调整列宽、想排序、想筛选都可能被一起禁掉。而业务上往往只希望“不能改值”其他操作照常。所以更合理的做法是单元格级权限控制配合 Facade API 在运行时动态判断。下面讲具体怎么落地。3. Facade API 实战把“只能填指定单元格”拆成可执行的代码3.1 Facade API 是什么为什么它比直接操作内核更靠谱univer 的内核Core是一套很底层的模块系统直接操作内核意味着你要理解Command、Mutation、Domain这些概念学习曲线很陡。Facade API 是官方提供的一层“门面”把常用操作封装成更直观的方法比如univerAPI.getActiveWorkbook()拿到当前工作簿worksheet.getRange(A1:C3).setValue(...)设置区域值worksheet.getRange(A1).getCellStyle()拿样式。我一开始图省事直接翻内核源码改 Mutation结果升级版本时全挂了。后来改用 Facade API虽然有些高级功能它还没暴露但稳定性好太多。对于“模板 填写”这种业务场景Facade API 基本够用实在不够再考虑自定义 Command。3.2 加载模板后如何批量设置只读假设模板设计者已经保存了一份 Workbook 快照里面用自定义元数据标记了可填写单元格。填写者加载后我们要做的是遍历所有单元格把没有标记的设为只读。Facade API 里没有直接的“遍历所有单元格”方法但可以通过getSheet()拿到工作表再用getRange()配合行列数来遍历。代码大概长这样const workbook univerAPI.getActiveWorkbook(); const worksheet workbook.getActiveSheet(); const rowCount worksheet.getMaxRows(); const colCount worksheet.getMaxColumns(); for (let r 0; r rowCount; r) { for (let c 0; c colCount; c) { const cell worksheet.getRange(r, c); const meta cell.getCellMeta(); // 假设有获取元数据的方法 if (!meta || !meta.editable) { cell.setLocked(true); // 伪代码实际 API 名称可能不同 } } }这里有个性能坑如果表格很大比如 1000 行 × 50 列双重循环会卡死。我的优化方案是只遍历有内容的区域用worksheet.getDataRange()拿到实际有数据的范围再在这个范围内遍历。另外设置只读的操作最好批量提交而不是逐个单元格调用否则会触发大量重渲染。3.3 拦截粘贴和拖拽只读控制的隐藏漏洞前面提到只设locked是不够的。用户可以通过 CtrlV 粘贴、拖拽填充柄、甚至删除行来绕过。univer 提供了事件拦截机制可以在这些操作发生前判断目标区域是否可编辑。以粘贴为例Facade API 里可以监听BeforeClipboardPaste之类的事件具体名称以文档为准在回调里检查粘贴目标区域是否包含只读单元格。如果包含就取消这次粘贴。univerAPI.onBeforeClipboardPaste((params) { const targetRange params.targetRange; if (containsLockedCell(targetRange)) { params.cancel true; // 阻止粘贴 // 可以在这里弹个提示 } });拖拽填充同理监听BeforeFill事件。删除行/列则监听BeforeDeleteRange。关键思路是所有会改变单元格值的操作都要过一遍权限检查。我一开始只拦了直接编辑结果测试时被用户用粘贴轻松绕过返工了一次。3.4 给可填写单元格加视觉提示光锁住还不够用户得知道“哪里能填”。univer 支持自定义单元格样式可以给可填写区域加个浅色背景或者边框。做法是在加载模板后遍历可填写单元格设置一个醒目的样式。但这里要注意样式和权限是两回事。你给单元格加了背景色不代表它就可编辑反过来可编辑的单元格也不一定非要加背景色。我见过有人把“可编辑”和“有背景色”绑死结果模板设计者想改个颜色把权限也改没了。正确的做法是两者独立配置只是视觉上保持一致。4. Canvas 渲染与 Node.js 工程化那些文档里不会写的坑4.1 Canvas 渲染的性能边界在哪里univer 的表格是用 Canvas 画的不是 DOM。这意味着它的性能上限比 DOM 表格高很多但也带来一些特殊问题。第一个问题是首屏渲染时间。如果表格很大Canvas 需要一次性画出所有可见区域初始化会慢。我的经验是超过 5000 个单元格的表格首屏加载要加 loading 状态否则用户会以为页面卡死。第二个问题是滚动时的重绘。univer 做了虚拟滚动只画可见区域但如果你在滚动事件里做了重计算比如动态权限判断就会掉帧。我的做法是权限判断只在加载时做一次结果缓存起来滚动时直接读缓存。第三个问题是导出和打印。Canvas 画出来的东西直接打印会糊。univer 提供了导出图片或 PDF 的能力但需要额外配置。如果业务有打印需求最好提前测试。4.2 Node.js 环境下的安装与版本选择univer 是前端库但它的构建和测试依赖 Node.js。关键词里出现了“node.js 22.12”说明新版本对 Node 有要求。我实测下来Node 18 LTS 也能跑但 Node 20 以上更稳因为一些构建工具链对旧版本支持不好。安装步骤没什么特别的但有两个坑第一不要用太老的 npm。univer 的依赖树里有几个包用了较新的 package.json 特性npm 6 会报错。建议 npm 9 以上。第二如果公司网络有代理记得配好 registry。这个不多说配不好连依赖都拉不下来。node -v # 确认版本 18 npm -v # 确认版本 9 npm install univerjs/core univerjs/facade4.3 和现有前端框架的集成方式univer 不绑定框架React、Vue、甚至原生 JS 都能用。但集成时有几个注意点容器尺寸univer 需要一个有明确宽高的容器否则 Canvas 画不出来。我见过有人把容器设成height: 100%但父元素没高度结果白屏。销毁时机组件卸载时要调用univer.dispose()否则会有内存泄漏。React 里放在useEffect的清理函数里。多实例一个页面里不要创建多个 univer 实例除非你确定需要。多个实例会争抢 Canvas 资源性能很差。5. 权限控制的边界与常见误判5.1 “只读”不等于“不可见”很多人把“锁定单元格”理解成“隐藏单元格”这是两码事。只读意味着用户能看到值但不能改隐藏意味着用户根本看不到。在预算填报场景里通常需要用户看到固定区的值比如科目名称、计算公式所以是只读而非隐藏。univer 支持隐藏行/列但那是另一个维度的控制。权限控制管的是“能不能改”隐藏控制管的是“能不能看”两者要分开设计。5.2 公式单元格的特殊处理如果固定区里有公式比如合计行用户虽然不能直接改但可能通过修改可填写区的值来间接影响公式结果。这是正常的也是业务需要的。但要注意公式的计算范围如果包含了只读单元格而只读单元格的值又被程序修改了公式会重新计算。这通常没问题但如果你的业务逻辑依赖“只读单元格的值绝对不变”就要小心。我的做法是在保存填写结果时只提取可填写单元格的值固定区的值以模板为准不信任前端传回来的固定区数据。这样即使前端被篡改后端也能保证数据一致性。5.3 多用户并发填写的冲突问题如果多个用户同时填写同一份模板univer 本身不提供协同能力协同需要额外的协同引擎。在“模板 填写”场景里通常是每个用户填自己的副本最后汇总。所以并发冲突不是大问题。但如果你要做“多人同时填一张表”那就需要引入协同层univer 有对应的协同方案但配置复杂度会上升一个量级。我的建议是如果业务允许尽量做成“每人一份副本”省掉很多麻烦。6. 从模板设计到数据回收的完整链路6.1 模板设计器的最小实现模板设计器不需要太复杂核心功能就三个画表格结构、标记可填写区、保存快照。univer 本身就是一个完整的表格编辑器你只需要在它的基础上加一个“标记”按钮。标记的逻辑可以很简单用户选中一个区域点“设为可填写”代码就给这个区域的每个单元格打上editable: true的元数据。保存时把整个 Workbook 序列化成 JSON 存到后端。6.2 填写页面的加载与提交填写页面加载时从后端拉取模板 JSON用 univer 加载然后执行权限设置把没有editable标记的单元格设为只读。用户填完后点提交代码遍历所有可填写单元格收集值发给后端。这里有个细节收集值时要用单元格的“显示值”还是“原始值”如果单元格有格式化比如日期、百分比显示值和原始值可能不一样。我的经验是存原始值展示时再格式化这样后端处理更方便。6.3 后端如何校验填写结果后端不能信任前端传来的数据。校验逻辑至少包括检查提交的单元格是否都在可填写区内检查值的类型是否符合模板定义比如数字字段不能传字符串检查必填项是否都填了。这些校验规则可以从模板 JSON 里提取不需要硬编码。我在项目里把校验规则也存进了模板的元数据里后端读取后动态校验模板改了校验规则也跟着变。7. 一些实测下来的经验与建议关于性能univer 的 Canvas 渲染在中等规模表格几千个单元格下非常流畅但如果你要做“全表遍历 逐单元格设置权限”一定要做范围限制和批量提交。我试过在 2000 行 × 30 列的表上逐单元格设只读卡了将近 10 秒改成只遍历数据区 批量提交后降到 1 秒以内。关于版本升级univer 还在快速迭代Facade API 偶尔会有破坏性变更。我的建议是锁定小版本号升级前先看 changelog别盲目追新。关于文档univer 的官方文档覆盖了核心概念但很多实战细节比如粘贴拦截、性能优化需要翻源码或社区讨论。遇到问题先搜 issue大概率有人踩过同样的坑。关于选型如果你的需求只是“展示一个只读表格”用普通 HTML 表格就够了没必要上 univer。但如果你需要“用户可编辑 精细权限控制 公式计算 大数据量”univer 是目前少有的能同时满足这几点的开源方案。最后分享一个我常用的调试技巧在开发阶段把 univer 的 Workbook 快照打印到控制台看看权限配置到底写进去了没有。很多时候问题不在代码逻辑而在配置根本没生效。这个习惯帮我省了不少排查时间。
