企业官网建设流程全解析

如果你以为用户要的只是一个“网页版 Excel”，那 Univer 这个项目看起来平平无奇；但如果你真正接过“给用户填写的在线表格”这种需求——打开页面，只能编辑你指定的几个格子，其他区域无论怎么双击、怎么粘贴、怎么快捷键清空都改不动——你就会理解为什么我说 Univer 的价值不在“渲染表格”，而在“控制表格”。这篇文章就围绕这个真实业务诉求展开：先帮你把 Univer 跑起来，再把“单元格可编辑性”这套机制彻底讲透，最后给出我踩坑之后的完整实现方案。适合那些正准备用 Univer 做数据采集、业务填报、在线调查表、权限化表格的前端开发者，以及想评估这个框架能不能扛住复杂交互场景的团队技术负责人。

1. 故事背景：大多数开源表格框架，都没解决“谁能编辑哪一个格”的问题

1.1 一个很常见的需求，却很难找到现成答案

我之前接到的需求特别朴素：给客户发一个链接，对方打开以后是一个表格，表格里预设好了一些字段，比如“项目名称”“预计费用”“到账日期”。客户只需要把灰色区域的全部锁定，亮白色区域能填，填完之后点一个按钮提交数据。

这个需求看起来简单，但真正落实的时候才发现，市面上很多开源表格框架默认把“整个页面”当成一个可编辑画布。用户鼠标点哪哪就能输入，右键菜单里一堆“插入行、删除列、清除内容”的选项，甚至按下 Delete 键就能把公式区清空。这要是发给客户，轻则填错数据，重则把表结构都改没了。

而 Univer 给我留下的第一印象就是：它是把“电子表格”和“交互控制”做在一起的项目，底层事件链路足够开放。你可以用它默认的完整能力，也可以把它拆成一套“只给用户看、只让用户填”的受控表格。这正是我想要的东西。

1.2 Univer 是谁，它和传统表格方案差异在哪

Univer 是一个基于 TypeScript 的本地优先电子表格解决方案。简单说，它用 Canvas 渲染表格界面，用一套统一的命令系统管理所有表格操作，同时支持多客户端协同编辑的底层设计。它提供的是一整套 SDK 级别的能力，而不是一个完整定死的产品形态。

很多人会拿它和 Handsontable、AG Grid、Luckysheet 这类框架比。我的个人感受是：

如果你只是在后台管理系统里做个数据网格，Handsontable 的成本可能更低；但如果你要把表格公开给终端用户去操作，并且要对“操作权限”做细致控制，Univer 的事件机制更值得研究。

1.3 这篇内容你能拿到什么

读完这篇文章，你会得到几样东西：

• 一套能直接跑起来的 Univer 初始化流程，以及我在初始化阶段踩过的坑；
• 对 Univer 命令系统的底层理解，知道“一个单元格为什么不能编辑”这件事到底由谁决定；
• 一个真正能用的“锁定表格 + 可填区域”实现方案，包含代码级别的步骤；
• 基于真实业务的扩展玩法，比如邀请制填写、单元格权限矩阵、敏感公式隐藏；
• 我在实际项目中遇到的 5 个隐蔽问题，每个都附了处理思路。

下面先解决一个现实问题：你的工程环境。

2. 搭建基础工程：先把一个能跑的 Univer 表格弄出来

2.1 最快启动路径

我建议你用 Vite 搭一个 React 项目，Univer 对 React 的支持比较顺。创建一个空目录后执行：

npm create vite@latest univer-demo -- --template react-ts cd univer-demo npm install

然后安装 Univer 相关的包。这里要特别提醒：Univer 依赖很多子包，安装的时候尽量一次性装齐，避免后面缺一个补一个，因为版本对齐问题很容易让人心态崩掉。

npm install @univerjs/core @univerjs/sheets @univerjs/sheets-ui @univerjs/ui @univerjs/sheets-formula @univerjs/design

你正在读这篇文章的时间点，Univer 的版本可能又变了。我踩过的经验是：优先看官方文档的“快速开始”，把所有包固定在同一版本区间。千万不要 core 装 0.1.x、ui 装 0.2.x 这种混搭版本，大概率会出现方法找不到的问题。

2.2 初始化代码骨架

创建一个src/UniverSheet.tsx或者直接在 App.tsx 里写都行。核心初始化逻辑大概是这样的：

import { Univer } from '@univerjs/core'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'; import { UniverUIPlugin } from '@univerjs/ui'; import { UniverFormulaEnginePlugin } from '@univerjs/sheets-formula'; export function createUniver(container: HTMLElement) { const univer = new Univer({ locale: 'zhCN', locales: { zhCN: import('@univerjs/locale/zh-CN'), }, }); // 注册表格核心插件 univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverFormulaEnginePlugin); // UI 层的插件，负责渲染表格壳子 univer.registerPlugin(UniverUIPlugin, { container, }); // 表格 UI 交互层 univer.registerPlugin(UniverSheetsUIPlugin); return univer; }

然后在组件里这样用法：

import { useEffect, useRef } from 'react'; function App() { const ref = useRef<HTMLDivElement>(null); useEffect(() => { if (!ref.current) return; createUniver(ref.current); }, []); return <div ref={ref} style={{ width: '100vw', height: '100vh' }} />; }

跑起来npm run dev，浏览器里应该出现一个可以编辑的空白表格。

这里有一个很重要的点：container必须是已经挂载到 DOM 里的元素，而且必须设置了宽高。我见过有人把容器高度写成 0，结果表格只渲染出十几像素的“一条线”，排查了半天。

2.3 初始化阶段容易踩的隐藏坑

第一个坑：中文语言包加载路径。

很多版本的 Univer 不把中文内置，需要你显式加载语言包。如果你用了 Vite，import('@univerjs/locale/zh-CN')这种动态导入是可行的，但如果你用的是 webpack，路径可能需要@univerjs/locale/lib/locale/zh-CN。我在实际项目里两种都遇到过，最靠谱的方式是看装完包以后 node_modules 里的实际目录结构。

第二个坑：插件注册顺序。

我测试过几次，把UniverSheetsUIPlugin注册在UniverSheetsPlugin之前，某些版本会出现表格没有工具栏的情况。虽然不一定报错，但为了稳妥，先注册核心插件，再注册 UI 插件，这个顺序不要反。

第三个坑：Canvas 渲染层级和自定义浮层的冲突。

Univer 的表格主体是基于 Canvas 架构，但它上面会承载一些 HTML 浮层，比如单元格编辑器、右键菜单、公式提示框。如果你们的页面里有很高的z-index弹窗，它们可能会盖住 Univer 的菜单，或者反过来被 Univer 的容器盖住。我的建议是初始化时给容器单独设一个 CSSz-index层级区间，并约定所有业务弹窗都高于这个区间。

只要基础工程跑通，后面的核心机制才有地方施展。

3. 核心机制拆解：单元格能不能编辑，到底由谁说了算

3.1 Univer 的命令系统：所有操作都从一道“门”里进出

这里需要先建立一个认知：Univer 的大多数用户操作，不是直接修改数据模型，而是先产生一个“命令”，命令再被分发出去，由相关模块执行。这个设计很像你办公室只有一扇大门，每个人要进办公室都得先经过前台登记，保安有权决定放行还是拦住。

比如用户双击一个单元格并输入内容，底层会产生一个编辑单元格的命令；用户按 Delete，会产生一个清除内容的命令；用户右键选择“插入行”，会产生一个插入行的命令。

而 Univer 在命令流转的链路上，给了我们一个操作点：可以在命令执行之前进行拦截。你完全可以写一段代码，判断“这个命令是否影响锁定区域”，如果影响，直接返回一个false，命令就被吞掉了，用户界面看起来就是“点了没反应”。

这比用 DOM 事件去阻止默认行为要可靠得多，因为不管用户是通过鼠标、键盘、快捷键、右键菜单还是脚本触发的操作，只要最终要走命令系统，都会被同一道闸拦住。

3.2 为什么不能简单用“锁定单元格”选项来实现

很多人在用类 Excel 软件时，脑海中第一反应是“单元格锁定”——Excel 里确实有“保护工作表”搭配“锁定单元格”这套机制。Univer 早期版本和当前版本对这套“工作表保护”的支持并不完整，即便在新版本里可能加上了保护功能，它的设计也更偏协作权限而非业务表单控制。

如果你在网上搜“Univer 锁定单元格”，可能会搜到一些设置单元格样式的方案，表面上看单元格变成灰色不可编辑了，但那只是一种“视觉暗示”。要是用户在灰色区域双击，依然可能唤起编辑器，或者通过右键菜单修改格式。

我的建议是不要依赖“锁定”这个单一机制，而是把“单元格可编辑性”抽象成三个层次的叠加：

1. 交互层控制：双击单元格不唤起编辑器；
2. 命令层控制：所有修改类命令都被过滤器拦截；
3. 视觉层控制：可编辑区域和不可编辑区域有清晰视觉区分。

这三个层次每一层都有各自的价值，缺一个都会产生体验漏洞。接下来我会完整展示这套实现。

3.3 另一道闸：右键菜单和快捷键往往被忽视

命令层拦截能挡住大多数直接操作，但有两个入口是新手特别容易漏掉的。

第一个是右键菜单。Univer 默认的右键菜单里有大量操作项，比如“清除内容”“插入行”“删除行”。用户右键点出来，点击菜单项，这同样会触发命令。如果你只拦截了双击编辑，没有拦截右键菜单里的清除命令，那用户选中锁定区域按“清除内容”，数据照样被清掉。

第二个是快捷键组合。Univer 默认支持Ctrl+A全选、Delete清除、Ctrl+C/V复制粘贴。问题在于用户全选以后，按一下 Delete，这个“清除内容”命令的作用范围是选中的多个区域。如果你在做范围判断时只看“当前激活单元格”，而没检查选区范围，就会漏掉大面积误删。

所以我们的拦截逻辑必须以“操作范围”为准，而不是以“当前光标所在单元格”为准。

4. 完整实现：把表格改成“可填单元格 + 其余锁定”的受控模式

4.1 先定义清楚：你的业务里哪些格子能被填写

技术实现之前，先做业务建模。我常用的方案是约定一张“配置表”：每个可编辑单元格用一个字符串标识，比如A2、B3，或者一段区间C5:F10。这个配置可以直接放进前端代码，也可以从后端动态下发，这样同一个 Univer 实例可以应对不同权限的访客。

举个例子，一张费用填报表的配置大概长这样：

// 可编辑区域的配置，可以来自后端 const editableRanges = [ { startRow: 1, endRow: 5, startColumn: 1, endColumn: 3 }, // B2:D6 { startRow: 8, endRow: 8, startColumn: 0, endColumn: 2 }, // A9:C9 ];

Univer 的行列下标从 0 开始，startRow: 1, endRow: 5对应的其实是 Excel 里的第 2 行到第 6 行。这个换算关系写代码的时候千万小心，我第一次写的时候把行列各加了 1，导致配置完全对不上。

封装一个判断函数：

function isCellEditable(row: number, column: number, ranges: Range[]) { return ranges.some( (r) => row >= r.startRow && row <= r.endRow && column >= r.startColumn && column <= r.endColumn ); }

这个函数会贯穿后面所有的拦截逻辑，是整个受控体系的地基。

4.2 第一步：拦截编辑命令，让点击无效区域时“哑火”

Univer 里最核心的拦截方式是通过命令服务。不同版本 API 名称可能有差异，但思路一致：在命令执行之前加入一个判断函数。下面这段代码是我在一个 React 组件里实际用过的模式：

import { CommandType, ICommandService } from '@univerjs/core'; function setupEditGuard(univerAPI: any, editableRanges: Range[]) { const commandService = univerAPI.getCommandService(); // 这些命令是需要被禁止的“写操作” const blockedCommands = new Set([ 'sheet.command.edit-cell', // 编辑单元格 'sheet.command.set-range-values', // 批量设置值 'sheet.command.clear-cell', // 清除单元格 'sheet.command.remove-row', // 删除行 'sheet.command.remove-col', // 删除列 'sheet.command.insert-row', // 插入行 'sheet.command.insert-col', // 插入列 ]); commandService.beforeCommand((command: any) => { if (!blockedCommands.has(command.id)) { return true; // 放行不影响受控区域的命令 } // 从命令参数里解析出操作涉及的行列范围 const ranges = extractRangesFromCommand(command); if (!ranges) return true; // 只要操作范围内包含任何不可编辑区域，就整个拦截 const containsLocked = ranges.some((range) => { for (let r = range.startRow; r <= range.endRow; r++) { for (let c = range.startColumn; c <= range.endColumn; c++) { if (!isCellEditable(r, c, editableRanges)) { return true; } } } return false; }); if (containsLocked) { // 可选：提示用户哪些区域不可操作 // toast('该区域不允许修改'); return false; // 取消命令 } return true; }); }

这里有一个关键细节：我没用“只看激活单元格”的方式，而是把命令涉及的所有单元格都遍历了一遍，只要碰到锁定区域就整体拦截。比如用户选中了 A1:B10，其中 B8 是锁定区，那整个操作都会被拦截，包括 A1:B7 里本来允许填写的部分也被一起拦住了。

你可能觉得这样太粗暴。但实际业务中，用户如果跨选区操作，说明他已经不太清楚哪些可以改哪些不能改，这时候给他一个“整体拦下”的反馈，比“悄悄改一部分、留一部分”更安全。如果你希望更精细，可以进一步区分：拦截后把选区裁剪到只保留可编辑部分，再执行命令，但那样实现复杂度会高很多，我目前只在内部工具里试过，公开给外部用户时默认采用整体拦截。

4.3 第二步：双击不唤起编辑器，连输入法输入也被挡住

命令层拦截解决的是“执行阶段”，但用户体验还存在一个漏洞：用户在锁定区域双击时，可能会弹出一个编辑器浮层，虽然最终提交会被拦截，但这个“闪一下”的交互非常令人困惑。更麻烦的是，有些版本里用户输入到一半，命令还没触发，界面上已经有临时内容了。

我采用的方案是拦截编辑器唤起逻辑。Univer 的 UI 层扩展机制里有编辑器的打开控制，不同版本开放程度不同。早期的做法是重写单元格编辑器的打开判断，新版我建议通过它的事件总线或者内部状态控制。

如果版本足够新，会支持类似下面的思路：

import { FEditorService } from '@univerjs/sheets-ui'; const editorService = univerAPI.getActiveEditorService(); // 在这个服务里注册一个 pre-open 校验

如果版本不支持，还有一个后备方案：监听选区变化，如果选区落到不可编辑区域，马上把编辑器关闭并撤销焦点。这个方法稍显笨重，但在旧项目迁移时很管用。

const selectionManager = univerAPI.getSelectionManager(); selectionManager.selector$.subscribe((selection) => { const current = selection?.currentCell; if (!current) return; const { row, column } = current; if (!isCellEditable(row, column, editableRanges)) { // 强制关闭可能打开的编辑器 editorService.closeEditor(); } });

这里要小心一个时序问题：用户先点了一个可编辑单元格，编辑器弹出，然后又用方向键把“选区光标”移到了锁定区域。这时候编辑器可能还开着。你要在每次选区变化时都重新校验，不能只在初次打开时校验一次。

4.4 第三步：右键菜单瘦身，把危险操作直接移除

右键菜单拦截是很多人最后才想起的一环。Univer 的右键菜单基于一套可扩展的菜单机制，我们可以按菜单项 ID 屏蔽掉不需要的功能。

我常用的方式是写一个菜单过滤器：

import { MenuPosition } from '@univerjs/ui'; univerAPI.getMenuService().registerMenuEventListener( MenuPosition.CONTEXT_MENU, (menuItems: any[]) => { // 过滤掉插入、删除、清除等对被保护表格有危险的项目 return menuItems.filter((item) => { const id = item.id || item.commandId || ''; if (id.includes('insert') || id.includes('remove') || id.includes('clear')) { return false; } return true; }); } );

具体过滤菜单的 API 名称在不同版本里确实有变化。我的建议是：如果文档找不到，优先看这个菜单服务返回的菜单项数组里有没有commandId字段，直接暴露出来的菜单项 ID 一般能对应到命令 ID，把危险命令过滤掉即可。

做完这一步，用户右键点击锁定区域，只会看到复制、粘贴这些无害操作，不会出现“插入行”“删除行”“清除内容”这些能破坏表格结构的入口。

4.5 视觉反馈：让用户一眼就知道哪里能填

用户打开页面，如果只有编辑时才能发现“这里不能填”，体验是不友好的。所以我在受控模式下一定会做两件事：

第一，给可编辑区域加明显的底色。通过 Univer 的样式接口，初始化时把所有可编辑范围设置为浅黄色或亮白色，锁定区域设置为浅灰色。

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); for (const range of editableRanges) { sheet.getRange(range.startRow, range.startColumn, range.endRow, range.endColumn) .setBackgroundColor('#fffbe6'); }

第二，给锁定区域设置一个不那么明显的边框或填充，让用户潜意识里知道这些地方“不归我管”。甚至可以在顶部加一行提示文案：“黄色区域可填写，灰色区域不可修改。”

还有一个细节：用户点击可编辑区域时，可以正常看到输入光标；但点击锁定区域时，最好连单元格的“高亮选中框”都去掉，否则用户会以为选中了就能编辑。Univer 可以通过选区样式接口控制选中高亮的颜色，这里我把选中高亮设为透明，避免误以为可编辑。

4.6 数据提交：把用户填好的内容读取出来

受控表格最终要落地到业务系统里，所以读取用户填写的数据是必做项。Univer 提供了便捷的数据读取接口：

function collectUserInput(univerAPI: any, editableRanges: Range[]) { const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const result: Record<string, string | number | boolean | null> = {}; for (const range of editableRanges) { for (let r = range.startRow; r <= range.endRow; r++) { for (let c = range.startColumn; c <= range.endColumn; c++) { const cellKey = `${String.fromCharCode(65 + c)}${r + 1}`; // A1 形式的坐标 const cellValue = sheet.getCell(r, c)?.value ?? null; result[cellKey] = cellValue; } } } return result; }

这里推荐只读取可编辑区域内的数据，而不是把整张表的数据都捞出来。原因有两个：第一，整表读取可能会有很多无意义的空值，增加传输量；第二，如果你把锁定区域里的公式结果也提交给后端，一旦公式因为协作因素重算，后端的数据可能和用户看到的不一样。

5. 真实业务扩展：从“锁定表格”到“权限表格”

5.1 场景一：给外部客户发一张“邀请填写表”

这种场景最适合用 Univer 实现。后端根据客户信息生成一个访问令牌，前端带着令牌请求/api/get-edit-ranges，后端返回这个客户可填写的区域配置，比如“老王只能填 C2:C10”“老李可以填 B2:E20”。前端拿到配置后执行受控初始化。

这样一套下来，同一个 Univer 页面就成了一个轻量级的“在线填报表单”，不需要把数据搬到传统表单系统里，保留了 Excel 的视觉习惯，同时权限控制由后端统一管理。

5.2 场景二：单元格权限矩阵——不同角色看到同一张表，能改的地方不一样

更进一步，你可以把 editableRanges 扩展成权限矩阵。同一个单元格，在不同用户视角下可能是锁定、可编辑或者只读可视。比如财务人员能看到“成本”列，但只能改“预算”列；销售助理能改“客户名称”，但看不到“成本”列。

Univer 支持列的隐藏和条件渲染，你可以结合后端下发的能力字段动态设置：

• 能否查看这列：通过列的隐藏接口控制；
• 能否编辑这列：通过受控范围配置控制；
• 能否看到公式结果：通过公式计算结果的格式化控制。

这个玩法在上周我刚做完的一个预算采集项目里效果很好，客户说“终于不用再传 Excel 文件来回改了”。

5.3 场景三：隐藏敏感公式，但保留填写的体验

还有一种常见情况：表格里有复杂公式，比如合计列=SUM(B2:B10)。如果用户能看到公式结构，可能会误触修改，或者直接抄走你的业务逻辑。锁定区域能防止修改，但用户仍然可能通过复制单元格看到公式文本。

解决思路是在初始化时对锁定区域的单元格做数值快照，并把公式单元格的值转为纯数值展示，同时阻止用户查看公式。Univer 的单元格数据模型支持设置显示值和原数据，可以在加载时遍历需要隐藏公式的区域，把显示值固定为计算结果，源数据里的公式字段不做展示。

6. 我在 Univer 受控表格上踩过的坑与最终处理方案

6.1 坑：双击锁定区域，编辑器会闪一下再关闭

这是一个非常影响观感的问题。用户明明点的是灰色区，结果一个输入框突然出现又消失，显得系统不稳定。

处理思路是把编辑器的打开时机延后，通过选区校验提前介入。我在代码里加入了对pointerdown事件的监听：如果按下鼠标时当前坐标对应的单元格是不可编辑的，就给该区域加一个“禁止”的状态标识，并在编辑器打开流程的最前面做终检。两个环节叠加之后，“闪一下”的现象基本消失。

6.2 坑：Ctrl+A 全选后按 Delete，把填好的数据全清空了

这是最危险的一个坑。全选后 Delete 会触发一个大范围清除命令，如果命令范围包含锁定区域，按照我的拦截逻辑应该会整单拦下。

但实测中发现，有些版本的全选命令会拆分成多个小命令逐个执行，先清除第一段，再清除第二段。每一个小段单独看可能都是“可编辑范围”，但合起来覆盖了锁定区域。

处理方案是给命令拦截增加一个“操作会话”跟踪：如果检测到同一次用户操作衍生出的多个命令，就把它们合并判定，一旦其中任何一个子命令涉及锁定区域，所有子命令都拦截掉。实现上可以给 UI 层增加一个事件周期标记。

6.3 坑：右键菜单的“粘贴”操作，可以绕过编辑拦截

用户从外部复制了一段文字，在表格里右键选择粘贴。如果粘贴的目标区域是锁定区，理论上会被命令拦截；但粘贴还可能以“设置单元格值”的方式执行，其命令 ID 跟普通编辑不同。

所以我维护了一个禁止命令的“黑名单”时，把粘贴、从剪贴板导入数据等命令也加了进去。同时建议对粘贴的内容做文本校验：如果粘贴的是富文本，Univer 可能自动附加样式，有时还会改变目标单元格的格式，哪怕只是贴到允许编辑的区域也会把表格样式搞乱。

6.4 坑：撤销（Undo）操作能突破拦截逻辑

用户先填了一个数字到可编辑区，然后把区域改成了锁定，再按Ctrl+Z，这个时候撤销操作可能尝试把之前的数据写回已经被锁定的单元格。我一开始没处理这种情况，结果测试时发现已经被锁定的单元格居然“复活”了。

解决方式是给撤销命令也加一道检查：如果是撤销类命令，把它影响的单元格范围再跑一遍可编辑性判断，如果涉及当前锁定区域，就改成“只恢复到非锁定单元格”或直接阻断。

6.5 坑：默认工具栏的“格式刷”和“样式面板”仍能改锁定区外观

最后要说的是工具栏。就算禁止了右键菜单，顶部工具栏里依然有字体颜色、背景色、合并单元格等按钮。这些操作也会产生命令。我最终的做法是直接隐藏顶部工具栏的大部分按钮，只保留“保存”和“导出”，或者干脆用自定义工具栏替换默认的。

如果你的业务场景完全不需要工具栏，可以只注册UniverSheetsPlugin和UniverSheetsUIPlugin，自己用业务按钮控制整个交互流程。这样反而最干净，控制力最强。

结尾想说的话

做 Univer 受控表格给我的最大感受是：不要把“禁止编辑”寄托在任何一个单点机制上。命令拦截、编辑器校验、菜单过滤、视觉提示、数据收集，这五件事要同时做，才能形成一面完整的安全网。每一层单独拿出来都有漏洞，但它们叠加在一起，就能给终端用户一种“这表本来就不能改那些地方”的天然感。如果你打算在自己的项目里复刻这套方案，建议从一个最小场景跑起——先锁死整张表，再慢慢放开一两个可填写单元格，把每一步的拦截日志打出来看，会比一上来就铺开全部逻辑轻松得多。希望这篇记录能帮你少走我走过的弯路。