我先说一个特别常见的真实场景：公司行政要做一张“部门费用报销收集表”，表头固定好，部门、报销人、日期这些直接用下拉选，报销金额、备注这两列留空给员工填，其余所有区域无论怎么双击、粘贴、拖动，都不能被改动。这种“用户定义表格 + 开放部分单元格 + 锁定其余单元格”的需求，在数据收集、问卷填报、内部表单、低代码平台上到处都是。这里要聊的项目标题是univer，一个基于 TypeScript 开发的在线表格系统，它天生就是为这种场景设计的。
Univer 不是那种只做前后端表单校验的简单表格插件，它是一个完整的在线办公套件，覆盖 Sheet（电子表格）、Doc（文档）、Slide（演示文稿）三种核心单元，并且自带 Canvas 渲染引擎、公式引擎、条件格式、数据透视和协同编辑 SDK。对我这种常年做 B 端工具的前端团队来说，Univer 最吸引人的点不是“能画一个表格”，而是它把“单元格权限控制”“模板定义”“在线协同”“公式联动”这些原本要分开拼装的底层能力，收拢到了同一个内核里。你不需要再从零搭一个类 Excel 的渲染引擎，也不需要自己硬造一套权限模型。
这篇文章我会从选型对比讲到权限控制的实操写法，再分享一些我踩过的新手坑。既有代码，也有思路，适合正在做在线办公、表单收集、低代码平台的前端开发，也适合产品和技术负责人用来评估方案。
1. 先搞清楚 Univer 是什么，以及它凭什么值得做技术选型
1.1 它到底是“升级版 Luckysheet”，还是完全不同的新东西
网络热词里经常把 Univer 和 Luckysheet 放在一起讨论，这是有原因的：Univer 的团队就是 Luckysheet 的原班人马，但 Univer 并不是 Luckysheet 的简单迭代，它是一次底层推倒重写。我在第一次看 Univer 源码时最直观的感受是，它不再用 DOM 表格来模拟 Excel 的滚动交互，而是用 Canvas 自绘渲染，滚动、选区、编辑交互全部走渲染引擎。这样就绕开了“表格单元格数量一多，DOM 节点爆炸导致卡顿”的经典瓶颈。
如果用一个生活类比，Luckysheet 像是一辆在原款车上不断加配的老车，Univer 则是基于同一套底盘需求重新设计的全新车型。它不只是 Sheet，还统一了 Doc 和 Slide，资源共享同一个 @univerjs/core 内核模块；后续如果要扩展文档编辑或 PPT 展示，不需要在不同产品栈之间横跳。模块化设计上，Univer 引入了插件机制，所有能力都能按需注册，比如公式引擎、数据透视、筛选、剪贴板、协同插件都不是默认全开，而是通过univer.registerPlugin(...)一个个挂进去。
这带来一个比较实际的收益：线上表格场景最怕的是“我只需要填数，却被迫加载了一个完整 Office 的重量级壳子”。Univer 可以通过插件裁剪，让一个轻量填报应用只保留必要的核心模块，首屏体积和运行内存压力都会小很多。
1.2 对比 Handsontable、SpreadJS 和传统只读表格方案
我不止一次被问到“为什么不直接用 Handsontable”或“SpreadJS 不是更成熟吗”。这里面的取舍，我在做技术选型时专门列过一个对比表：
| 方案 | 单元格级权限 | 渲染性能 | 协同能力 | 授权成本 | 适用场景 |
|---|---|---|---|---|---|
| Handsontable | 支持单元格编辑器禁用，但偏向组件级控制，不擅长全功能表格 | 中上，大数据量依赖虚拟滚动 | 需要自己接 OT/Yjs | 商业授权 | 嵌入页面的数据录入组件 |
| SpreadJS | 支持工作表保护和单元格锁定，权限控制强 | 较强，Spread 内核渲染成熟 | 云方案需额外购买协同模块 | 较高 | 类 Excel 的复杂业务系统 |
| Luckysheet | 早期版本保护功能较弱，权限模型不完整 | 依赖 DOM，超大表格有性能墙 | 协同方案需自己构建 | 开源免费 | 轻量在线表格 |
| Univer | 工作簿/工作表/单元格多层级保护，配合公式引擎，能力完整 | Canvas 自绘，滚动和交互性能稳健 | 官方提供协同 SDK 和示例，整合更顺 | 开源免费（注意商业授权条款） | 在线办公、低代码、填报类产品 |
这个表不是要论证 Univer 样样第一，而是明确一个观点：如果你的需求停留在“页面里嵌一个用户可编辑的表格，做做前端校验”，Handsontable 确实轻便；但一旦需求升级为“管理员定义模板、普通用户只能填白名单区域、公式自动汇总、多人同时在线协作”，那已经不是表格组件问题，而是完整的在线表格引擎问题。Univer 恰好覆盖了这个层次。
1.3 Univer 能解决的核心问题：从“表格展示”到“协作编辑权限体系”
Univer 带给业务最大的增量，是把表格从“展示工具”升级成“业务闭环载体”。举个内部系统例子：以前表单收集场景，前端要写一堆规则去禁用 input、拦截粘贴、监听 change；现在 Univer 的模型层本身就带保护机制，非法编辑在命令层就会被拒绝，前端 UI 上双编辑、拖拽填充这些动作都会同步受限，前端拦截和后端数据校验不再是两层皮。
同时，Univer 的公式引擎是内置的。比如“金额”列开放填写，“汇总”格直接用=SUM(D2:D20)写成公式并锁定，普通用户即使看到汇总结果也无法篡改公式。这种能力在纯表格组件里往往需要大量胶水代码，在 Univer 里是原生特性。再加上数据验证（下拉、日期限制、必填提示）和条件格式，基本就覆盖了一个线上填报系统的所有交互要求。
2. 需求拆解：把“部分单元格可改，其他单元格不可改”翻译成技术语言
2.1 先理解“支持用户定义表格”的真实含义
“支持用户定义表格”这句话听起来很宽泛，但在具体业务里，它至少包含两层角色：一层是模板设计者（通常是管理员或运营），负责创建表头、设置字段说明、预设公式和校验规则；另一层是数据填写者（通常是员工或终端用户），负责在开放区域内录入数据。Univer 里这两类角色可以通过不同的“保护配置+数据视图”来区分。
管理员定义表格的过程，本质上是在 Univer 上执行一串“写模型”的操作，比如 insertRow、设置单元格值、设置公式、设置数据验证。这个过程可以用 Univer 的模板下发机制实现：管理员在编辑状态下完成后，把工作簿快照（WorkbookData）持久化到后端；普通用户打开时加载同一份快照，但 Univer 会带上管理员设置的保护信息，于是看到的是一个“可以填一部分”的受限表格。
2.2 哪些行为必须被“锁定”才算真正不可修改
很多初级方案会把“锁定”理解为禁用编辑器或者给单元格加 readonly，这在交互层面是不够的。一个真正不可修改的单元格，至少要拦截这些路径：
- 直接双击进入编辑状态；
- 通过顶栏输入或公式栏输入；
- 从其他单元格复制粘贴覆盖；
- 拖动填充柄（fill handle）批量填充；
- 通过剪贴板批量粘贴多行多列；
- 通过“查找替换”或批量操作批量写入。
Univer 的保护机制是在命令/模型层面拦截，而不是只做 UI 禁用。只要设置了lock: true并关闭相应的 allow 权限，上述动作中的大多数都会被统一拒绝掉。更关键的是，保护规则可以细化到“单元格区域级别”，不用一个单元格一个单元格去标记，直接用setRangeProtection之类的接口把整个可编辑区域声明出来即可。
2.3 梳理一个最小可用权限模型
在设计系统时，我习惯先把权限模型拆成几个层级，避免后面业务越接越乱：
| 层级 | 概念 | 业务例子 |
|---|---|---|
| 工作簿保护 | 防止添加/删除/隐藏工作表、重命名 Sheet、改变工作簿结构 | 管理员不允许普通用户新增 Sheet |
| 工作表保护 | 防止插入/删除行列、修改列宽行高、排序等结构性操作 | 不允许员工拖拽调整表格列宽，避免布局被破坏 |
| 单元格/区域保护 | 锁定具体单元格或区域，只有白名单区域允许编辑 | 金额列、备注列开放；姓名列、部门列锁定；汇总公式列锁定 |
这个三层模型的好处是职责清晰：工作簿层管“表有多少页”，工作表层管“表结构长什么样”，单元格层管“哪些格子能写”。Univer 的实现很接近这个划分，所以业务方不用再自创权限框架，直接映射即可。
3. 实操落地：用 Univer 从零实现“可填项放行、其他锁定”
3.1 初始化实例：先跑起一个最轻的 Univer Sheet
老规矩，先做环境准备。Univer 的安装方式在不同版本间变化很快，我习惯直接基于官方 preset 包来初始化，避免手工拉扯一堆插件依赖。下面是一个可直接运行的初始化骨架：
import '@univerjs/preset-sheets/style.css'; import { Univer, LocaleType } from '@univerjs/core'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'; import { UniverRenderEnginePlugin } from '@univerjs/engine-render'; import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'; import { UniverUIPlugin } from '@univerjs/ui'; import { DEFAULT_WORKBOOK_DATA } from './workbook-data'; const univer = new Univer({ locale: LocaleType.ZH_CN, locales: { zhCN: () => import('@univerjs/core/locale/zh-CN'), }, }); univer.registerPlugin(UniverRenderEnginePlugin); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsUIPlugin); univer.registerPlugin(UniverFormulaEnginePlugin); univer.registerPlugin(UniverUIPlugin, { container: 'app', header: true, toolbar: true, }); univer.createUnit({ id: 'workbook-1', type: 'UNIVER_SHEET', name: '报销单收集表', sheets: DEFAULT_WORKBOOK_DATA, });这里有几个容易踩的细节：第一，UniverUIPlugin的container必须是页面中已经存在的 DOM 元素，且容器要有明确的宽度和高度，否则表格会渲染成零尺寸；第二，locale 配置如果不完整，UI 会出现英文和中文混杂，或者干脆白屏。我建议在开发早期就把locales配好，别等上线前再补。第三，不同版本的包名后缀可能从@univerjs/preset-sheets变成其他形式，还是要以官方文档和你锁定的版本为准。
初始化完成后，页面会出现一个完整的在线表格，但这只是第一步。现在这个表格所有单元格都是可编辑的，还要继续加保护。
3.2 准备“管理员定义模板”的核心数据
接下来要构造DEFAULT_WORKBOOK_DATA。我拿“部门费用报销收集表”举例，结构大概是：
- 第一行：大标题“X 月部门费用报销收集表”；
- 第二行：表头，包括“部门”“姓名”“费用类型”“报销金额”“发生日期”“备注”“汇总”；
- 第三到第二十行：普通用户的填写区域；
- 第二十二行：汇总行，放公式。
对应的基础数据大概是：
export const DEFAULT_WORKBOOK_DATA = { sheetOrder: ['sheet-01'], sheets: { 'sheet-01': { id: 'sheet-01', name: '报销单', cellData: { 0: { 0: { v: 'X 月部门费用报销收集表', s: 'bold,fontSize12' }, }, 1: { 0: { v: '部门' }, 1: { v: '姓名' }, 2: { v: '费用类型' }, 3: { v: '报销金额' }, 4: { v: '发生日期' }, 5: { v: '备注' }, 6: { v: '汇总' }, }, 21: { 0: { v: '总额' }, 3: { f: '=SUM(D3:D20)' }, }, }, rowCount: 30, columnCount: 10, }, }, };单元格对象里用v表示静态值，用f表示公式，这个模型和 Excel 的思维很接近。要注意的是，公式字符串里的单元格范围必须是实际存在的行，比如=SUM(D3:D20)，如果范围里包含空白单元格，公式引擎也会正常计算为 0，但是汇总结果会跟着用户录入实时更新。
3.3 权限放行：把“只许填白名单”落到保护配置里
这一步是整个需求的核心。Univer 的保护能力分为几个层级，我们需要给工作表和工作簿都加上保护，然后专门把可编辑区域放出来。参照官方文档和当前版本 API，配置可以这样组织：
const protection = { workbookProtection: { lock: true, allow: { addSheet: false, deleteSheet: false, renameSheet: false, }, }, sheetProtection: { lock: true, allow: { insertRow: false, insertColumn: false, deleteRow: false, deleteColumn: false, editObjects: false, selectLockedCells: true, selectUnlockedCells: true, sort: false, }, }, rangeProtections: [ { range: { startRow: 2, endRow: 19, startColumn: 0, endColumn: 5 }, allowEdit: true, }, ], };这个配置的语义可以分三层理解：
- 工作簿上锁后，普通用户无法新增/删除/重命名工作表；
- 工作表上锁后，行列插入删除、排序、对象编辑这些结构性操作全部被禁掉；
- 最后通过
rangeProtections把“表格标题区、表头区、汇总行”之外的“第3行到第20行的 A-F 列”声明为可编辑区域。
这里有个关键点要特别提示：selectLockedCells: true这个配置很反直觉。很多人以为锁定了就不该让用户选中，实则不然。在实际业务中，用户虽然不能编辑锁定格子，但仍然需要能选中、查看、复制其中的内容，比如复制一个固定编号去别处查询。所以我的建议是，常规填报表保持“锁定格子可选、可复制，但不可编辑”；如果涉及敏感数据不想被复制，再单独关掉选中权限。后面我会在踩坑部分详细讲。
3.4 用数据验证和公式联动做收口，让用户填不了非法内容
只有保护机制，还不够解决业务问题。实际用户在填“报销金额”时可能会填负数，填“发生日期”时可能手滑写成文本，这时候就需要数据验证（DataValidation）上场。Univer 提供的数据验证能力类似 Excel 的“数据有效性”，可以直接给 D 列设置数字规则：
const dataValidation = { type: 'number', operator: 'greaterThan', formula: 0, allowBlank: false, showErrorMessage: true, errorMessage: '报销金额必须大于 0', };比如费用类型这一列，可以直接用“下拉列表”来约束取值范围，减少手输不一致的脏数据。Univer 的 UI 上会弹出下拉箭头，用户选了才算填了，比后端反复校验要省不少事。
同时，汇总行公式是=SUM(D3:D20)，而汇总格所在的F22和“总额”标签格都不在可编辑白名单区域内，所以普通用户只能看到汇总结果，改不了计算逻辑。这一整套下来，表单收集的完整性就实现了：可填的地方填数据，不可填的地方稳如磐石。
3.5 提交数据：怎么把用户填好的内容安全地送回后端
用户填完之后，前端需要把结果提交到后端。Univer 不限制你怎么取数据，最直接的方式是拿到当前活动工作表，然后读取指定区域的二维数组：
const activeSheet = univer.getActiveUnit().getActiveSheet(); const values = activeSheet.getRange(2, 0, 18, 6).getValues(); const payload = values.map((row) => ({ department: row[0], name: row[1], expenseType: row[2], amount: row[3], date: row[4], remark: row[5], })); await fetch('/api/expense/submit', { method: 'POST', body: JSON.stringify(payload), });这里有一个我在项目里踩过的坑：getRange(startRow, startCol, rowCount, colCount)的行列起点是 0 基准还是 1 基准，不同版本表现会有差异。建议拿到数据后先打点日志确认，别直接上生产。另外，如果要监听用户实时编辑而不是等最后提交，可以用 Univer 的编辑事件监听器，比如univer.getActiveUnit().onCommandExecuted(...)去捕捉哪些命令被执行了，但高频事件一定要做防抖合并，否则协同和上报的压力会很大。
4. 进阶玩法：协同、按角色区分配与数据上报闭环
4.1 多人协同与单元格保护如何共存
填报类应用一旦有“多人同时填一张表”的需求，就会遇到一个灵魂问题：两个用户同时编辑同一个格子，谁先谁后？Univer 的协同方案建立在命令（Command）+ OT/Yjs 的机制上，官方也提供了协作 SDK 示例。团队落地时要注意，协同服务和业务后端要分开部署，前端通过 WebSocket 接入，操作以命令形式广播。
协同和单元格保护不冲突的原因在于：保护是在命令执行前的校验层，任何被锁定的编辑命令在产生阶段就被本地或服务端判定为不合法，根本不会进入合并流程。也就是说，普通用户在协同环境里点一个锁定格子，连编辑弹窗都不会出现，也就不会产生冲突操作。
4.2 同一份模板，不同角色看到不同的可编辑区域
真实业务里经常还有“谁填哪块”的差异化需求。比如一个项目计划表，项目经理能改任务工期，普通成员只能填自己的进度备注。Univer 本身不一定内置完整的 RBAC 系统，但可以在加载工作簿快照后，根据当前登录用户的角色动态生成不同的保护配置。
实际操作上，我会让后端在返回模板时附带一个editableRanges字段，前端拿到后把它转换成 Univer 的rangeProtections。比如项目经理的editableRanges包含 C 列和 D 列，普通成员的只包含 F 列。这样一套模板代码，不同角色看到的就是不同“可填地图”。这个过程不需要重新复制一份 Sheet，只是保护配置不同，数据模型始终是同一份。
4.3 表格只是前端壳子，核心是数据回路
做表格类系统，最容易犯的错是把所有精力放在“界面能不能填”上，忽略了数据回到业务系统的回路。我在实际业务里是把 Univer 的表格快照和业务数据结构解耦的：Univer 表格是用户的编辑视图，后端 SQL 表才是数据真相。
提交的时候，前端提交的是“结构化后的业务数据”（比如上面的payload），后端验证通过后写入数据库，再返回一个提交编号。如果业务要求审批流程，后端可以在收到提交后锁定这部分区域的再次编辑权限，或者给前端下发新的保护配置。这样，Univer 只是负责“收集人怎么填”，审批流、权限流仍然是业务系统自己的主管。
5. 常见问题与排查技巧实录
5.1 保护配置明明写了，为什么还是能编辑锁定单元格
这是新手最常遇到的问题，我排查下来通常有三种原因。
第一种，锁定的范围写错了。Univer 的range参数是 0 基准的，比如第 1 行表头对应startRow: 0，如果你写的endRow比实际行数大，可能会把可编辑区域和锁定区域重叠。重叠区域的行为优先级在 Univer 里是有明确规则的，但为了避免歧义，我建议设计和调试时先在控制台打印一遍最终生效的 protection 对象。
第二种，selectLockedCells和可编辑性混淆。用户能选中有锁定的单元格不表示它可以编辑，但如果你发现用户能双击进入编辑，说明保护配置没有真正落到 Sheet 上。Univer 的很多设置类接口都是“通过命令改变模型”，而不是改一个普通 JavaScript 对象就能即时生效的，必须走命令管线，比如使用ISheetCommand相关的命令。我倾向于直接在createUnit的初始化数据里就把 protection 塞进工作簿快照，这样模型一创建就是带锁的。
第三种，版本 API 变动。Univer 迭代很快，早期版本和当前版本的setWorkbookProtection、setSheetProtection方法签名可能不同，甚至被重命名。遇到接口不生效，我建议直接去官方文档或 GitHub 仓库找到对应版本的类型定义，把鼠标悬停到方法上看返回类型，比猜要高效得多。
5.2 大数据量表格滚动卡顿、首屏加载慢怎么破
Univer 虽然用 Canvas 渲染，但数据量上来以后，公式引擎的初始化开销和 UI 插件的序列化开销依然存在。我处理 10 万行以上数据时，会做这几件事：
- 关闭不必要的插件，比如没有演示文稿需求时不要注册 Slide 相关插件；
- 首屏只加载前 50 行数据，剩余数据等滚动到视口附近再按需拉取；
- 对公式的范围做收敛，避免整列引用（
=SUM(D:D)会增大计算范围，能用D3:D20就不要用整列）； - 如果开启协同，把快照的同步频率做节流。
Univer 的默认体验已经不错，但“默认够用”和“生产级”之间还有一段路，需要结合实际数据规模做针对性优化。
5.3 公式不重算、汇总结果不更新是怎么回事
公式不重算，首先要怀疑数据是不是被外部方式直接改掉的。比如通过setRangeValues直接写模型但没走公式引擎的刷新流程，公式可能不会立即重算。更稳妥的方式是，所有业务写入都走 Univer 的编辑命令或者官方 API 提供的高层方法，这样公式引擎会自动参与计算。
还有一个高频问题：公式单元格的显示值是文本而非计算结果。检查单元格对象里没有f字段，或者数据快照里f写成了v。我曾见过同事把{ f: '=SUM(...)' }和{ v: '=SUM(...)' }写混，导致单元格内容变成纯文本“=SUM(...)”，一点都不报错，但就是不计算。
5.4 常见问题速查表
| 现象 | 可能原因 | 处理思路 |
|---|---|---|
| 白屏 | 容器无尺寸 / locale 缺失 / 插件未注册 | 检查容器宽高、补齐 locale、按官方模板初始化 |
| 锁定格子仍可编辑 | protection 未进模型 / range 范围写反 | 在初始化快照里直接设置 protection，打印确认 |
| 公式显示为文本 | f与v混淆 | 统一用f字段，删除v |
| 多端数据不一致 | 未走命令管线直接改模型 | 尽量使用官方命令 API，建议接协同 SDK |
| 滚动卡顿 | 大数据量 + 插件过多 | 裁剪插件、数据分段、收敛公式范围 |
| 下拉校验弹不出 | 数据验证范围与可编辑区域不重叠 | 确认校验所作用的 range 和 editable range 交集 |
6. 最后再分享一个我实际项目里的体会
这个标题看起来只是“一个在线表格”，但认真把需求做完后，你会发现它背后牵涉的是模板设计、权限模型、数据校验、公式计算和协同一致性的完整链路。在我最近做的一个内部数据收集系统中，Univer 确实帮我省掉了以前大量繁琐的 DOM 禁用和剪贴板拦截代码，把更多精力留给了业务层。
如果你正在为“让用户填表格但又不让他乱改”发愁，我的建议是先别急着抄代码，而是花一个下午把 Univer 的保护层级和数据模型研究透。一旦理解了“保护是模型层的、不是 UI 层的”这个核心观点，再往上搭业务就非常顺。这里没有银弹，但 Univer 确实是我目前用下来最顺手的一条路。
