Univer 这个名字最近在搞前端表格、做在线办公产品的圈子里讨论得挺多。简单说它是一个开源的、面向开发者的在线表格/文档/幻灯片协同方案底层用 TypeScript 写的渲染走 Canvas设计上让开发者可以像搭积木一样在自己的系统里嵌入一个具备 Excel 核心能力的在线表格。很多团队拿它来做数据填报、台账录入、项目看板甚至直接把后端返回的 JSON 渲染成可交互报表。这篇文章想聊的核心不是 Univer 的完整文档而是把“用户在页面里填一个表格但只能填我们指定的单元格其他单元格不能动”这个真实需求拆开揉碎讲清楚实现思路、关键代码、日常会遇到哪些坑。如果你正好想在自己的后台系统里做个“自定义报表 受限填报”的功能这篇内容可以直接拿去做方案参考。1. 为什么是 Univer在线表格项目的关键选型逻辑1.1 在线表格最难做的不是渲染而是状态管理先说一个我自己的体会。如果你尝试从零手写一个“像 Excel 的网页表格”刚开始会觉得无非就是一个二维数组加 HTML table真正写起来才发现单元格选区、公式依赖、行列拖拽、复制粘贴、撤销重做、滚动虚拟化、协同冲突每一项都是深水区。一个最简单的例子用户在表格里选中 A1:A10然后按 Delete你要不要触发布局重算如果 A1 是标题、A2 是公式公式又引用了 C1你需要重新计算的范围怎么确定更不用说多用户同时编辑同一个 Sheet版本怎么合并。所以“表格”在里面不是 UI 组件的问题是一个状态引擎问题。Univer 的价值就在这里它把数据模型、渲染层、交互层、命令系统拆开了开发者主要跟 Sheet 数据模型和命令打交道而不是跟 Canvas 像素坐标打交道。1.2 Univer 的核心构成和项目分层思路Univer 的项目结构是典型的“核心 插件”模式。核心包负责 WorkBook、WorkSheet、CellData、Range 这些数据结构以及命令注册、撤销栈、公式引擎、样式模型。插件的思维是你在原来只是“能渲染表格”的基础上加上公式能力、条件格式、数据透视、图表、协同编辑、导入导出每一块能力都是一个独立插件包。这对真实项目非常友好。比如你只需要一个“用户填数据 提交”的场景你甚至可以不引入完整 Excel 编辑工具栏只保留数据填充、单元格校验、表单提交按钮。我在项目里实际就是这么干的。Univer 官网的文档中心列了一堆插件很多人一上来全装结果包体巨大编译也慢。实际上 Univer 支持按需装配你应该先想清楚自己到底需要哪些能力。比如我要做的填报系统核心需要的是渲染一个多行多列的表格允许用户在指定单元格内输入文本/数字其他单元格锁定不可编辑提交时校验必填项后端保存数据下次打开时回填这里面几乎不需要公式、不需要图表、不需要协同编辑。所以按需装配是正确解法。1.3 对比其他方案为什么不选 Excel 在线预览也不选纯前端 table 组件市面上“前端表格”方向的方案不少。一类是纯展示型比如用 Ant Design Table、el-table 渲染数据这种方案对“填报”场景很别扭因为你要自己实现单元格编辑状态、键盘导航、选区管理工作量大。另一类是 Excel 预览型比如后端用 LibreOffice / OnlyOffice 转 PDF 或者 HTML这种方案交互能力弱用户没法直接在网页里录入。还有一类是 Heavy 级套件比如 SpreadJS、Handsontable它们很强但商用授权要评估而且前端框架深度集成时闭源方案的可控性不如开源。Univer 恰好卡在一个平衡点上开源协议友好组件化装配公式引擎和协同能力都有原生支持 Canvas 高性能渲染万行级别的数据滚动基本不掉帧。另外在线表格场景最容易被忽略的一点是「用户心智」。做数据填报用户并不希望“点一下编辑按钮整张表才能编辑”而是希望“光标的落点决定了可编辑状态”。Univer 的单元格访问控制和 hover/selected 状态反馈做得好这种细节对用户体验影响极大。后面展开聊。2. 核心机制Univer 单元格只读与自定义编辑的设计原理2.1 先理解 Univer 的编辑流程命令系统是入口Univer 对表格做的任何操作本质上都是“命令”。选中单元格后按下键盘输入系统会生成一条编辑单元格的命令命令里带着目标单元格行列号、新值、旧值、样式变更等载荷然后把命令提交给命令服务。这套机制的好处是所有修改都有统一入口方便做权限校验有统一的撤销重做栈协同编辑时容易做操作合并因此实现“某个单元格不能被用户修改”最简单也最可控的办法就是在命令执行前注册一个拦截器。拦截器拿到命令载荷判断目标区域是否允许编辑不允许就直接拒绝执行表格内容不会发生任何变化。这比“监听 input 事件然后回滚值”要安全得多因为它是在数据层拦截而不是在 UI 层补救。2.2 权限模型命令无法覆盖的“操作行为”也要考虑只拦截“修改单元格内容”的命令你会发现还漏了不少口子。比如“删除行列”“拖拽填充柄覆盖区域”“粘贴数据到锁定区域”“通过公式引用的方式间接影响锁定单元格”。严格点说如果要做严谨的只读控制拦截范围应该包括EDIT_CELL编辑单元格内容PASTE粘贴数据覆盖DELETE_RANGE删除区域内容INSERT_ROW/DELETE_ROW增删行导致数据错位FILL_HANDLE拖拽自动填充CLEAR_RANGE一键清空内容我在 Univer 里实现权限控制时习惯把所有可能修改数据的命令类型都放一个白名单里。可编辑单元格走白名单不可编辑单元格一律拦截。如果你只是拦了一个EDIT_CELL用户照样可以用 CtrlV 覆盖锁定区域这是个非常容易踩的坑。2.3 设置禁止编辑区域可以用 Univer 的内置权限或自建公式映射Univer 本身提供基础权限能力但实际业务往往有更复杂的规则。比如“A 用户能填 B2 到 B10B 用户能填 C2 到 C10”“同一个 Sheet 里不同角色看到可编辑区不一样”。这些规则明显不是固定的“设置保护工作表”而是基于用户角色的动态计算。我的做法是把可编辑范围作为表格的额外元数据存储下来比如在服务端保存一个 JSON{ sheetId: sheet-001, editableRanges: [ { rowStart: 1, rowEnd: 9, colStart: 1, colEnd: 1 } ] }前端加载表格后根据当前登录用户身份从后端拿到这份权限配置然后注册命令拦截器。这样同一份表格文件不同登录用户打开后表现完全不一样。数据层和权限层天然解耦。3. 实操用 Univer 搭建一个“用户填数、其他单元格锁定”的表单3.1 环境准备和依赖安装我用的是 Vite React TS 的工程Univer 官方对 React 没有强绑定你用 Vue 或者纯 TS 也都能接。先装核心依赖npm install univerjs/core univerjs/sheets univerjs/ui univerjs/sheets-ui univerjs/sheets-formula univerjs/sheets-numfmt univerjs/engine-formula如果你的场景只需要基础填报上面的包足够。注意univerjs/sheets-formula如果你完全用不到公式可以不装减少打包体积。但保险起见如果表格里有汇总行还是装上。这里有一个很现实的点Univer 版本更新特别快接口名在不同 minor 版本之间有差异。一定先把版本锁死并且在项目里跑通一个最简渲染 Demo 后再往上叠功能。我最初就是直接照最新文档写结果发现univerjs/ui依赖版本和univerjs/sheets-ui对不上编译报错浪费不少时间。3.2 初始化表格实例和渲染容器初始化 Univer 实例的关键代码大概是这样的import { Univer } from univerjs/core; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverSheetsUIPlugin } from univerjs/sheets-ui; import { UniverFormulaPlugin } from univerjs/sheets-formula; import { UniverNumfmtPlugin } from univerjs/sheets-numfmt; const univer new Univer({ locale: zhCN, plugins: [ UniverSheetsPlugin, UniverFormulaPlugin, UniverNumfmtPlugin, UniverSheetsUIPlugin ] }); const workbook univer.createUnit(workbookData);这里的核心流程是createUnit你传入一个描述 WorkBook 的 JSON 对象Univer 负责把它渲染出来。WorkbookData 的大致结构是{ id: book-001, name: 项目周报, sheetOrder: [sheet-001], sheets: [ { id: sheet-001, name: Sheet1, rowCount: 100, columnCount: 20, cellData: { 0: { 1: { v: 姓名 }, 2: { v: 本周完成事项 } } } } ] }注意单元格数据是“行列坐标 → 单元格对象”的嵌套结构行号从 0 开始。这个结构刚接触时很容易糊涂尤其是从二维数组思维转过来的人。我踩过一个很丢人的坑给rowCount设了 100但准备在第 101 行填充内容结果一直不显示后来才意识到行列坐标是零基的第 100 行其实是第 101 个位置。3.3 注册命令拦截器禁止编辑锁定区域创建 Univer 实例后通过命令服务注册拦截器import { FUniver } from univerjs/core; const univerAPI FUniver.newAPI(univer); univerAPI.getCommandService().beforeCommandExecute((command) { const type command.type; const payload command.payload; const editableRanges getCurrentUserEditableRanges(); if (isWriteCommand(type)) { const { row, column, ranges } extractEditRange(payload); const shouldBlock !isRangeAllowed(row, column, editableRanges); if (shouldBlock) { // 返回 false 表示阻止执行 return false; } } return true; });其中isWriteCommand判断命令类型是否属于“会写入数据”的类型extractEditRange从命令载荷里提取目标区域。对于粘贴、填充这类涉及多格的操作需要解析出全部目标区域做交集判断。只要有一个单元格不在权限范围内整个命令就应该拦截。拦截之后最好给用户一个 toast 提示告诉用户“当前单元格为只读不可编辑”。这个提示可以用 Univer UI 插件提供的消息接口也可以自己在全局事件里触发关键是不能让用户觉得是表格卡死了。3.4 通过样式和交互反馈强化“可编辑”心智只做逻辑拦截用户在表格里点到一个锁定单元格时还是会出现光标闪烁、输入但没反应的诡异体验。所以要配合视觉反馈把所有不可编辑的单元格设置成灰色背景同时设置光标样式为not-allowed。Univer 里给单元格设置样式是通过样式模型{ 0: { 1: { v: 姓名, s: { cl: { rgb: #f0f0f0 }, ht: 2, vt: 0 } } } }其中cl是背景色ht是水平对齐vt是垂直对齐。不可编辑区域的背景色用浅灰可编辑区域用白色用户扫一眼就知道哪里能填。另外一个细节是Univer 默认选中整个行列时会显示行列头高亮如果整个 Sheet 允许勾选“整行/整列”用户也可以通过调整行列结构来破坏锁定区域。我通常会把选定模式限制为“单元格选择”或者在权限拦截时同时拦截行列操作命令。3.5 从表格取值并提交到后端用户填完数据后需要读取内容。Univer 的FUniverAPI 可以直接获取单元格值const value univerAPI.getActiveWorkbook()? .getActiveSheet()? .getCellValue(row, column);批量提交时遍历可编辑范围传感器取数据组装成 JSONPOST 给后端。这里有个建议不要在后端解析“二维数组”而是提交[{ row, column, value }]这样的稀疏结构。因为实际填报时用户不会把所有格子都填满稀疏结构更紧凑后端存 MongoDB 或 MySQL JSON 字段都不费劲。提交后的数据如何回填到表格里两种方式。如果只是回显重新调用createUnit时把cellData带上即可。如果是长时间停留在页面上有人改了数据需要局部刷新某几个单元格则可以用setCellValueAPI 只更新指定单元格避免整个 Sheet 重新渲染导致滚动位置丢失。4. 权限控制之外的性能与协作问题4.1 大数据量单元格渲染优化Univer 的 Canvas 渲染让它在万级单元格数据量下依然流畅但要注意两点一是不要一次性写入超大 cellData 对象数据加载采用分页/懒加载对首屏更友好二是避免频繁调用局部 setCellValue 引发全量重绘Univer 内部做了脏区域合并但如果你在循环里连续修改几百个单元格最好合并成一次命令提交。我自己测试过一个场景一次性向表格写入 2 万行、每行 10 列的业务数据。直接塞 cellData 会导致首次渲染卡顿明显但页面滚动起来后很流畅。如果数据量再大建议后端做聚合后再下发或者只加载前 N 行滚动到底部加载更多。表格毕竟是“人看”的一屏最多看到几十行没必要把几十万数据一次性塞给前端。4.2 多人同时编辑同一张表的数据冲突如果只是做“填报表单”通常不需要实时协同。但如果你扩展成在线协作场景Univer 的协同能力就需要后端配合。Univer 前端负责把本地操作变成操作序列服务端负责合并和广播。最麻烦的冲突场景是两个人同时编辑同一个单元格A 填“完成”B 填“进行中”最终以谁的版本为准我的建议是在这个场景里引入“单元格级时间戳”概念。每次提交后端存储时带updatedAt回填到表格时比较版本如果本次提交前发现某个单元格的值已经被别人改过就弹出冲突提示让用户决定是否覆盖。这个方案比实时 CRDT 合并更容易实现对业务也更贴近实际。4.3 权限控制的逻辑校验必须放在后端这一点必须反复强调前端拦截只是提升用户体验不是安全手段。任何前端代码都能被绕过恶意用户直接用 devtools 调 Univer API 或者直接改 payload 就能把数据写进锁定单元格。所以后端接口必须重新校验“该用户对目标单元格是否有编辑权限”。做法很简单提交数据时后端拿到用户身份 单元格坐标集合去权限表里查一遍。常见套路是SELECT 1 FROM editable_range WHERE sheet_id ? AND role_id ? AND ? BETWEEN col_start AND col_end AND ? BETWEEN row_start AND row_end如果坐标集合里有任何一格查不到权限记录直接拒绝整批提交或跳过无权限单元格并返回提示。接口的返回值要清楚告诉前端哪些行成功、哪些行被拒绝前端据此展示部分失败状态。这是生产环境的基本要求。5. 常见报错与排查心得5.1 问题速查表现象大概率原因排查方向单元格输入没反应无报错命令拦截器返回 false但没有提示检查 beforeCommandExecute 里是否所有写命令都拦截了可编辑区域也被锁了行列号判断用了 1 基Univer 是 0 基检查 extractEditRange 解析出的 row/column 与后台配置是否一致整个 Sheet 渲染成空白createUnit 传入的 workbookData 缺失必要字段检查 sheets 数组里是否传入id缺少 id 会导致初始化异常公式不计算只显示输入文本缺少 univerjs/sheets-formula 插件安装公式插件并确认在 Univer 初始化时注册粘贴数据时把只读单元格清空了只拦截了 EDIT_CELL没拦截 PASTE增加 PASTE / FILL_HANDLE / CLEAR_RANGE 拦截切换用户角色后权限没变权限拦截器在创建实例时写死用户切换后未更新不要用全局变量缓存权限每次命令执行前从当前登录态读取5.2 调试小技巧Univer 的FUniver暴露了很多调试方法。开发时可以在控制台直接执行univerAPI.getActiveWorkbook()?.getSheets().forEach(sheet { console.log(sheet.getName(), sheet.getRowCount(), sheet.getColumnCount()); });确认表格实例是否正常加载。再比如我想确认命令请求到底走没走到拦截器可以在beforeCommandExecute里加一个开发环境日志开关打印所有命令类型。等确认没有漏网命令类型了再关掉日志。这个过程其实就是测试“所有可能修改数据的行为”都走统一入口是排查权限漏洞最有效的手段。5.3 版本升级带来的一些迁移坑Univer 还在快速迭代期前后接口变化非常快。我遇到的比较典型的坑是从0.1.x升级到0.2.x时创建 Univer 实例的插件注册方式从数组式变成了对象式。社区里的示例代码、博客、甚至官网文档都可能滞后。所以建议升级版本前先看官方 CHANGELOG在一个分支里升级并跑通最小 Demo不要大规模一键升级先把一个关键页面迁过去验证无回归再逐步替换如果遇到Cannot read properties of undefined之类的报错优先检查插件和核心包的版本匹配度。Univer 的包是同时发版的版本号不一致会直接导致底层 API 对不上。6. 再往后还能扩展什么目前这套方案已经支撑了内部一个数据周报工具。管理员在后台用 Univer 定义表格模板比如标题、表头、字段说明然后给销售、运营、研发各角色开放不同区域。每个人打开表格只看到自己能填的地方。提交后数据落到后端的cell_value表周报生成人一键导出 Excel 或 PDF。这个模式还可以继续扩展。比如单元格级校验规则必填、数字范围、日期格式Univer 支持在提交时做校验你可以在命令拦截器里拿新值跑正则或者函数校验失败就直接拒绝同时 toast 提示错误。单元格下拉选项。业务上“状态字段”其实不希望用户乱填Univer 的 DataValidation 能力可以配置下拉列表但如果你不想引入额外的插件也可以在拦截器里自己校验枚举值。表单联动。比如选了“部门 A”下一列自动带出“负责人”这种联动逻辑可以用公式也可以在前端监听单元格值变化后动态 setCellValue。用前端监听的好处是逻辑不依赖公式引擎好调试。导出权限。表格导出时也要按角色过滤不能让用户拿权限模板导出全量数据。这个通常在后端的导出服务里做前端 Univer 直接调用后端接口生成文件。最后说一点我自己的感受Univer 是一个值得关注的开源项目它的弹性和工程化程度在线表格里算是相当不错的。但它的学习曲线不算平缓尤其是命令体系、插件体系这些概念刚接触时会觉得不如直接写一个table直观。咬牙把这套抽象理解透后面做任何“在线编辑排版类”功能都会轻松很多。如果只是要一个给用户填数据的页面从头搭建重型渲染引擎不划算把 Univer 塞进去权限控制做扎实再把提交校验处理稳完事。这就是我目前觉得最省心的一条路。
Univer单元格锁定与权限控制：在线表格受限填报最佳实践
Univer 这个名字最近在搞前端表格、做在线办公产品的圈子里讨论得挺多。简单说它是一个开源的、面向开发者的在线表格/文档/幻灯片协同方案底层用 TypeScript 写的渲染走 Canvas设计上让开发者可以像搭积木一样在自己的系统里嵌入一个具备 Excel 核心能力的在线表格。很多团队拿它来做数据填报、台账录入、项目看板甚至直接把后端返回的 JSON 渲染成可交互报表。这篇文章想聊的核心不是 Univer 的完整文档而是把“用户在页面里填一个表格但只能填我们指定的单元格其他单元格不能动”这个真实需求拆开揉碎讲清楚实现思路、关键代码、日常会遇到哪些坑。如果你正好想在自己的后台系统里做个“自定义报表 受限填报”的功能这篇内容可以直接拿去做方案参考。1. 为什么是 Univer在线表格项目的关键选型逻辑1.1 在线表格最难做的不是渲染而是状态管理先说一个我自己的体会。如果你尝试从零手写一个“像 Excel 的网页表格”刚开始会觉得无非就是一个二维数组加 HTML table真正写起来才发现单元格选区、公式依赖、行列拖拽、复制粘贴、撤销重做、滚动虚拟化、协同冲突每一项都是深水区。一个最简单的例子用户在表格里选中 A1:A10然后按 Delete你要不要触发布局重算如果 A1 是标题、A2 是公式公式又引用了 C1你需要重新计算的范围怎么确定更不用说多用户同时编辑同一个 Sheet版本怎么合并。所以“表格”在里面不是 UI 组件的问题是一个状态引擎问题。Univer 的价值就在这里它把数据模型、渲染层、交互层、命令系统拆开了开发者主要跟 Sheet 数据模型和命令打交道而不是跟 Canvas 像素坐标打交道。1.2 Univer 的核心构成和项目分层思路Univer 的项目结构是典型的“核心 插件”模式。核心包负责 WorkBook、WorkSheet、CellData、Range 这些数据结构以及命令注册、撤销栈、公式引擎、样式模型。插件的思维是你在原来只是“能渲染表格”的基础上加上公式能力、条件格式、数据透视、图表、协同编辑、导入导出每一块能力都是一个独立插件包。这对真实项目非常友好。比如你只需要一个“用户填数据 提交”的场景你甚至可以不引入完整 Excel 编辑工具栏只保留数据填充、单元格校验、表单提交按钮。我在项目里实际就是这么干的。Univer 官网的文档中心列了一堆插件很多人一上来全装结果包体巨大编译也慢。实际上 Univer 支持按需装配你应该先想清楚自己到底需要哪些能力。比如我要做的填报系统核心需要的是渲染一个多行多列的表格允许用户在指定单元格内输入文本/数字其他单元格锁定不可编辑提交时校验必填项后端保存数据下次打开时回填这里面几乎不需要公式、不需要图表、不需要协同编辑。所以按需装配是正确解法。1.3 对比其他方案为什么不选 Excel 在线预览也不选纯前端 table 组件市面上“前端表格”方向的方案不少。一类是纯展示型比如用 Ant Design Table、el-table 渲染数据这种方案对“填报”场景很别扭因为你要自己实现单元格编辑状态、键盘导航、选区管理工作量大。另一类是 Excel 预览型比如后端用 LibreOffice / OnlyOffice 转 PDF 或者 HTML这种方案交互能力弱用户没法直接在网页里录入。还有一类是 Heavy 级套件比如 SpreadJS、Handsontable它们很强但商用授权要评估而且前端框架深度集成时闭源方案的可控性不如开源。Univer 恰好卡在一个平衡点上开源协议友好组件化装配公式引擎和协同能力都有原生支持 Canvas 高性能渲染万行级别的数据滚动基本不掉帧。另外在线表格场景最容易被忽略的一点是「用户心智」。做数据填报用户并不希望“点一下编辑按钮整张表才能编辑”而是希望“光标的落点决定了可编辑状态”。Univer 的单元格访问控制和 hover/selected 状态反馈做得好这种细节对用户体验影响极大。后面展开聊。2. 核心机制Univer 单元格只读与自定义编辑的设计原理2.1 先理解 Univer 的编辑流程命令系统是入口Univer 对表格做的任何操作本质上都是“命令”。选中单元格后按下键盘输入系统会生成一条编辑单元格的命令命令里带着目标单元格行列号、新值、旧值、样式变更等载荷然后把命令提交给命令服务。这套机制的好处是所有修改都有统一入口方便做权限校验有统一的撤销重做栈协同编辑时容易做操作合并因此实现“某个单元格不能被用户修改”最简单也最可控的办法就是在命令执行前注册一个拦截器。拦截器拿到命令载荷判断目标区域是否允许编辑不允许就直接拒绝执行表格内容不会发生任何变化。这比“监听 input 事件然后回滚值”要安全得多因为它是在数据层拦截而不是在 UI 层补救。2.2 权限模型命令无法覆盖的“操作行为”也要考虑只拦截“修改单元格内容”的命令你会发现还漏了不少口子。比如“删除行列”“拖拽填充柄覆盖区域”“粘贴数据到锁定区域”“通过公式引用的方式间接影响锁定单元格”。严格点说如果要做严谨的只读控制拦截范围应该包括EDIT_CELL编辑单元格内容PASTE粘贴数据覆盖DELETE_RANGE删除区域内容INSERT_ROW/DELETE_ROW增删行导致数据错位FILL_HANDLE拖拽自动填充CLEAR_RANGE一键清空内容我在 Univer 里实现权限控制时习惯把所有可能修改数据的命令类型都放一个白名单里。可编辑单元格走白名单不可编辑单元格一律拦截。如果你只是拦了一个EDIT_CELL用户照样可以用 CtrlV 覆盖锁定区域这是个非常容易踩的坑。2.3 设置禁止编辑区域可以用 Univer 的内置权限或自建公式映射Univer 本身提供基础权限能力但实际业务往往有更复杂的规则。比如“A 用户能填 B2 到 B10B 用户能填 C2 到 C10”“同一个 Sheet 里不同角色看到可编辑区不一样”。这些规则明显不是固定的“设置保护工作表”而是基于用户角色的动态计算。我的做法是把可编辑范围作为表格的额外元数据存储下来比如在服务端保存一个 JSON{ sheetId: sheet-001, editableRanges: [ { rowStart: 1, rowEnd: 9, colStart: 1, colEnd: 1 } ] }前端加载表格后根据当前登录用户身份从后端拿到这份权限配置然后注册命令拦截器。这样同一份表格文件不同登录用户打开后表现完全不一样。数据层和权限层天然解耦。3. 实操用 Univer 搭建一个“用户填数、其他单元格锁定”的表单3.1 环境准备和依赖安装我用的是 Vite React TS 的工程Univer 官方对 React 没有强绑定你用 Vue 或者纯 TS 也都能接。先装核心依赖npm install univerjs/core univerjs/sheets univerjs/ui univerjs/sheets-ui univerjs/sheets-formula univerjs/sheets-numfmt univerjs/engine-formula如果你的场景只需要基础填报上面的包足够。注意univerjs/sheets-formula如果你完全用不到公式可以不装减少打包体积。但保险起见如果表格里有汇总行还是装上。这里有一个很现实的点Univer 版本更新特别快接口名在不同 minor 版本之间有差异。一定先把版本锁死并且在项目里跑通一个最简渲染 Demo 后再往上叠功能。我最初就是直接照最新文档写结果发现univerjs/ui依赖版本和univerjs/sheets-ui对不上编译报错浪费不少时间。3.2 初始化表格实例和渲染容器初始化 Univer 实例的关键代码大概是这样的import { Univer } from univerjs/core; import { UniverSheetsPlugin } from univerjs/sheets; import { UniverSheetsUIPlugin } from univerjs/sheets-ui; import { UniverFormulaPlugin } from univerjs/sheets-formula; import { UniverNumfmtPlugin } from univerjs/sheets-numfmt; const univer new Univer({ locale: zhCN, plugins: [ UniverSheetsPlugin, UniverFormulaPlugin, UniverNumfmtPlugin, UniverSheetsUIPlugin ] }); const workbook univer.createUnit(workbookData);这里的核心流程是createUnit你传入一个描述 WorkBook 的 JSON 对象Univer 负责把它渲染出来。WorkbookData 的大致结构是{ id: book-001, name: 项目周报, sheetOrder: [sheet-001], sheets: [ { id: sheet-001, name: Sheet1, rowCount: 100, columnCount: 20, cellData: { 0: { 1: { v: 姓名 }, 2: { v: 本周完成事项 } } } } ] }注意单元格数据是“行列坐标 → 单元格对象”的嵌套结构行号从 0 开始。这个结构刚接触时很容易糊涂尤其是从二维数组思维转过来的人。我踩过一个很丢人的坑给rowCount设了 100但准备在第 101 行填充内容结果一直不显示后来才意识到行列坐标是零基的第 100 行其实是第 101 个位置。3.3 注册命令拦截器禁止编辑锁定区域创建 Univer 实例后通过命令服务注册拦截器import { FUniver } from univerjs/core; const univerAPI FUniver.newAPI(univer); univerAPI.getCommandService().beforeCommandExecute((command) { const type command.type; const payload command.payload; const editableRanges getCurrentUserEditableRanges(); if (isWriteCommand(type)) { const { row, column, ranges } extractEditRange(payload); const shouldBlock !isRangeAllowed(row, column, editableRanges); if (shouldBlock) { // 返回 false 表示阻止执行 return false; } } return true; });其中isWriteCommand判断命令类型是否属于“会写入数据”的类型extractEditRange从命令载荷里提取目标区域。对于粘贴、填充这类涉及多格的操作需要解析出全部目标区域做交集判断。只要有一个单元格不在权限范围内整个命令就应该拦截。拦截之后最好给用户一个 toast 提示告诉用户“当前单元格为只读不可编辑”。这个提示可以用 Univer UI 插件提供的消息接口也可以自己在全局事件里触发关键是不能让用户觉得是表格卡死了。3.4 通过样式和交互反馈强化“可编辑”心智只做逻辑拦截用户在表格里点到一个锁定单元格时还是会出现光标闪烁、输入但没反应的诡异体验。所以要配合视觉反馈把所有不可编辑的单元格设置成灰色背景同时设置光标样式为not-allowed。Univer 里给单元格设置样式是通过样式模型{ 0: { 1: { v: 姓名, s: { cl: { rgb: #f0f0f0 }, ht: 2, vt: 0 } } } }其中cl是背景色ht是水平对齐vt是垂直对齐。不可编辑区域的背景色用浅灰可编辑区域用白色用户扫一眼就知道哪里能填。另外一个细节是Univer 默认选中整个行列时会显示行列头高亮如果整个 Sheet 允许勾选“整行/整列”用户也可以通过调整行列结构来破坏锁定区域。我通常会把选定模式限制为“单元格选择”或者在权限拦截时同时拦截行列操作命令。3.5 从表格取值并提交到后端用户填完数据后需要读取内容。Univer 的FUniverAPI 可以直接获取单元格值const value univerAPI.getActiveWorkbook()? .getActiveSheet()? .getCellValue(row, column);批量提交时遍历可编辑范围传感器取数据组装成 JSONPOST 给后端。这里有个建议不要在后端解析“二维数组”而是提交[{ row, column, value }]这样的稀疏结构。因为实际填报时用户不会把所有格子都填满稀疏结构更紧凑后端存 MongoDB 或 MySQL JSON 字段都不费劲。提交后的数据如何回填到表格里两种方式。如果只是回显重新调用createUnit时把cellData带上即可。如果是长时间停留在页面上有人改了数据需要局部刷新某几个单元格则可以用setCellValueAPI 只更新指定单元格避免整个 Sheet 重新渲染导致滚动位置丢失。4. 权限控制之外的性能与协作问题4.1 大数据量单元格渲染优化Univer 的 Canvas 渲染让它在万级单元格数据量下依然流畅但要注意两点一是不要一次性写入超大 cellData 对象数据加载采用分页/懒加载对首屏更友好二是避免频繁调用局部 setCellValue 引发全量重绘Univer 内部做了脏区域合并但如果你在循环里连续修改几百个单元格最好合并成一次命令提交。我自己测试过一个场景一次性向表格写入 2 万行、每行 10 列的业务数据。直接塞 cellData 会导致首次渲染卡顿明显但页面滚动起来后很流畅。如果数据量再大建议后端做聚合后再下发或者只加载前 N 行滚动到底部加载更多。表格毕竟是“人看”的一屏最多看到几十行没必要把几十万数据一次性塞给前端。4.2 多人同时编辑同一张表的数据冲突如果只是做“填报表单”通常不需要实时协同。但如果你扩展成在线协作场景Univer 的协同能力就需要后端配合。Univer 前端负责把本地操作变成操作序列服务端负责合并和广播。最麻烦的冲突场景是两个人同时编辑同一个单元格A 填“完成”B 填“进行中”最终以谁的版本为准我的建议是在这个场景里引入“单元格级时间戳”概念。每次提交后端存储时带updatedAt回填到表格时比较版本如果本次提交前发现某个单元格的值已经被别人改过就弹出冲突提示让用户决定是否覆盖。这个方案比实时 CRDT 合并更容易实现对业务也更贴近实际。4.3 权限控制的逻辑校验必须放在后端这一点必须反复强调前端拦截只是提升用户体验不是安全手段。任何前端代码都能被绕过恶意用户直接用 devtools 调 Univer API 或者直接改 payload 就能把数据写进锁定单元格。所以后端接口必须重新校验“该用户对目标单元格是否有编辑权限”。做法很简单提交数据时后端拿到用户身份 单元格坐标集合去权限表里查一遍。常见套路是SELECT 1 FROM editable_range WHERE sheet_id ? AND role_id ? AND ? BETWEEN col_start AND col_end AND ? BETWEEN row_start AND row_end如果坐标集合里有任何一格查不到权限记录直接拒绝整批提交或跳过无权限单元格并返回提示。接口的返回值要清楚告诉前端哪些行成功、哪些行被拒绝前端据此展示部分失败状态。这是生产环境的基本要求。5. 常见报错与排查心得5.1 问题速查表现象大概率原因排查方向单元格输入没反应无报错命令拦截器返回 false但没有提示检查 beforeCommandExecute 里是否所有写命令都拦截了可编辑区域也被锁了行列号判断用了 1 基Univer 是 0 基检查 extractEditRange 解析出的 row/column 与后台配置是否一致整个 Sheet 渲染成空白createUnit 传入的 workbookData 缺失必要字段检查 sheets 数组里是否传入id缺少 id 会导致初始化异常公式不计算只显示输入文本缺少 univerjs/sheets-formula 插件安装公式插件并确认在 Univer 初始化时注册粘贴数据时把只读单元格清空了只拦截了 EDIT_CELL没拦截 PASTE增加 PASTE / FILL_HANDLE / CLEAR_RANGE 拦截切换用户角色后权限没变权限拦截器在创建实例时写死用户切换后未更新不要用全局变量缓存权限每次命令执行前从当前登录态读取5.2 调试小技巧Univer 的FUniver暴露了很多调试方法。开发时可以在控制台直接执行univerAPI.getActiveWorkbook()?.getSheets().forEach(sheet { console.log(sheet.getName(), sheet.getRowCount(), sheet.getColumnCount()); });确认表格实例是否正常加载。再比如我想确认命令请求到底走没走到拦截器可以在beforeCommandExecute里加一个开发环境日志开关打印所有命令类型。等确认没有漏网命令类型了再关掉日志。这个过程其实就是测试“所有可能修改数据的行为”都走统一入口是排查权限漏洞最有效的手段。5.3 版本升级带来的一些迁移坑Univer 还在快速迭代期前后接口变化非常快。我遇到的比较典型的坑是从0.1.x升级到0.2.x时创建 Univer 实例的插件注册方式从数组式变成了对象式。社区里的示例代码、博客、甚至官网文档都可能滞后。所以建议升级版本前先看官方 CHANGELOG在一个分支里升级并跑通最小 Demo不要大规模一键升级先把一个关键页面迁过去验证无回归再逐步替换如果遇到Cannot read properties of undefined之类的报错优先检查插件和核心包的版本匹配度。Univer 的包是同时发版的版本号不一致会直接导致底层 API 对不上。6. 再往后还能扩展什么目前这套方案已经支撑了内部一个数据周报工具。管理员在后台用 Univer 定义表格模板比如标题、表头、字段说明然后给销售、运营、研发各角色开放不同区域。每个人打开表格只看到自己能填的地方。提交后数据落到后端的cell_value表周报生成人一键导出 Excel 或 PDF。这个模式还可以继续扩展。比如单元格级校验规则必填、数字范围、日期格式Univer 支持在提交时做校验你可以在命令拦截器里拿新值跑正则或者函数校验失败就直接拒绝同时 toast 提示错误。单元格下拉选项。业务上“状态字段”其实不希望用户乱填Univer 的 DataValidation 能力可以配置下拉列表但如果你不想引入额外的插件也可以在拦截器里自己校验枚举值。表单联动。比如选了“部门 A”下一列自动带出“负责人”这种联动逻辑可以用公式也可以在前端监听单元格值变化后动态 setCellValue。用前端监听的好处是逻辑不依赖公式引擎好调试。导出权限。表格导出时也要按角色过滤不能让用户拿权限模板导出全量数据。这个通常在后端的导出服务里做前端 Univer 直接调用后端接口生成文件。最后说一点我自己的感受Univer 是一个值得关注的开源项目它的弹性和工程化程度在线表格里算是相当不错的。但它的学习曲线不算平缓尤其是命令体系、插件体系这些概念刚接触时会觉得不如直接写一个table直观。咬牙把这套抽象理解透后面做任何“在线编辑排版类”功能都会轻松很多。如果只是要一个给用户填数据的页面从头搭建重型渲染引擎不划算把 Univer 塞进去权限控制做扎实再把提交校验处理稳完事。这就是我目前觉得最省心的一条路。
