企业官网建设流程全解析

1. 为什么会盯上 univer：Web 表格场景的老问题和新思路

做前端时间久了，凡是和表格、报表、数据录入沾边的需求，基本都逃不过同一种纠结：到底是用原生表格硬调样式，还是直接嵌一个成熟的开源表格库，又或者干脆做个Excel文件上传下载把活儿丢给桌面端。

先说个真实的背景。我前两年接过一个在线数据管理后台的改造，需求听起来不复杂：让运营同学能在浏览器里直接编辑一份多 Sheet 的工作簿，要支持公式联动，还要记录谁改过哪个单元格。当时查了一圈，可选方案无非是选几个老牌组件库封装，看着功能够用，但真要塞进项目里就发现一堆问题——样式主题和我们自己的设计系统怎么都撞不到一起，公式引擎是黑盒，想扩展一个自定义函数得翻半天文档，而且协作能力基本停留在“最后保存的人说了算”的状态。后来代码越写越多、需求越堆越奇怪，本质上是底层架构扛不住，不是我们团队不行。

univer 就是在这个背景下进入视野的。它不是一个简单包装 Excel 功能的 UI 组件，而是一套面向 Web 的表格引擎，核心逻辑用 TypeScript 写，支持 Sheet、Doc、Slide 三大文档类型，整体采用插件化架构，从单元格渲染、公式计算到协同编辑、数据校验都有独立的模块。更直观地说，它就是想在浏览器里重建一个接近桌面办公软件体验的配套基础设施，让前端调用方只关心自己的业务逻辑，而不必从零发明一套行列模型。

这篇文章不会讲太多概念层面的东西，重点放在三块：univer 到底怎么设计和组织模块、实际集成的具体做法、以及跑起来之后容易被忽略的细节坑。如果你是那种正在犹豫要不要引入它的前端工程师，或者已经看完文档但想找点“过来人经验”的开发者，这篇应该能帮你少绕一段弯路。

2. univer 的核心架构：一张实时协作的表格背后分了几层

想用好 univer，第一步不是看怎么调 API，而是先理解它的整体分层。因为它的插件机制特别强，如果一开始没有按“核心 + 插件 + 业务接入”的思维去组织代码，后面很容易把功能写成一团乱麻。

2.1 核心引擎、UI 层和命令系统的边界

univer 从架构上看可以粗略分成三层：底层是文档数据模型和计算公式引擎，中间是命令系统（Command），上层才是你在页面上看到的各种 UI 控件和交互逻辑。数据模型与 UI 是分离的，这一点非常关键——你可以只把 univer 当做一个处理公式和单元格状态的数据引擎，自己写一套渲染层；也可以直接用官方提供的 UI 组件，省掉大量样式工作。

如果拿一个传统框架类比，命令系统就像是 Redux 里的 Action + Reducer：用户点工具栏、改单元格、删 Sheet，后台都转成一个个结构化的命令对象，统一走分发、执行、撤销、重做的链路。在 univer 的视野里，一个“操作”不应该直接去改底层数据，而是应该先构造成命令，再由命令去操作数据模型。这样做的好处非常明显：协作场景下每个前端实例都在做同一套逻辑，只要命令顺序一致，最终状态就能对齐；撤销重做也不是拍脑袋去保存每一帧快照，而是基于命令的反向执行来实现。

我见过不少人在最初集成 univer 的时候，把重点放在“渲染出来好不好看”，结果一碰到多端协同、多人同时输入，就发现底层模型跑偏了。核心原因就是绕过了命令系统，直接通过外部引用来改单元格数据，一旦 UI 刷新策略和命令流水线不一致，整个文档状态就跟天书一样。因此看 univer 的源码时，不用被一大堆装饰器和依赖注入吓到，你只需要抓住一条主线：数据模型是唯一的可信数据源，状态变更全部走命令。

2.2 插件系统为什么值得认真对待

如果只把 univer 当成一个表格组件，你可能会忽略它是按照插件化思路组织的。它官方提供了很多子模块，比如公式引擎、条件格式、数据校验、查找替换、协作评论等，每一个都可以作为独立插件引入，也可以按需定制。

这个设计带来的实际好处是：你不需要因为想用“数据校验”就把整个文档编辑器和图表系统全都装进来。反过来也成立，如果你的业务需要一套自定义的面板来修改单元格格式，你完全可以在 univer 的插件机制里注册自己的 UI 入口，甚至替换掉官方默认的工具栏。我们在实际项目里就把默认的顶部工具栏大部分按钮都隐藏了，只保留字号、加粗、对齐和合并单元格几个高频操作，再配合一套自己做侧的配置面板，整体看起来和产品原生功能几乎没有违和感。

另外，插件之间的通信也是按照事件和命令来组织的，而不是大家互相 import 对方的内部类。跨插件调用会通过依赖注入拿到 Facade，这种方式初看有点绕，但一旦业务模块变多，你会庆幸边界划得很清楚。打个比方，它更像在模块之间定了“接口契约”，而不是让所有代码共享一个全局变量。

2.3 数据模型与表格渲染的拆分

univer 的底层数据模型并不是直接绑定 DOM 结构。它用一套自己的行列索引、单元格引用和 Sheet 状态来描述整个文档，渲染只是对数据模型的一个“解释”。官方默认用 Canvas 来绘制表格区域，而不是堆大量 DOM 节点，所以在处理几万行数据的时候滚动性能会比普通表格组件好不少。

还有一点值得留意的，是 univer 的“Workbook → Worksheet → Range / Cell”的层级关系。Workbook 是最外层的工作簿，Worksheet 对应了一个个 Sheet 标签页，Range 则是对单元格区域的抽象的引用。业务开发时，你的绝大多数交互都是在定位 Range 和读写单元格数据。理解了这个映射关系，再去读 API 文档就会非常顺畅。

3. 30 分钟集成一个带公式和样式的在线表格

现在开始进入实操环节。我会以目前最常用的方式为例，用一个普通的前端项目做基础演示，让你跑通一个带公式、样式和基础交互的表格模块。这里选 Vue 3 搭配 Vite 做示例，React 场景下思路完全一致，只是挂载方式略微不同。

3.1 安装依赖时的最小组合

univer 官方推荐使用分包引入的方式，不需要一次性拉一个巨大的产物体积。基础环境通常需要以下依赖量级：

• @univerjs/preset-sheets：一个预设包，封装了基础表格所需的核心能力，比手动逐个安装子模块省事。
• @univerjs/core：数据模型、命令系统等基础能力。
• @univerjs/sheets-ui：表格 UI 渲染和交互层。
• @univerjs/ui：通用 UI 基础设施，比如工具栏、弹窗、右键菜单。
• @univerjs/sheets-formula：公式引擎，不装就没有公式计算能力。

如果只是希望快速验证，直接装一个预设包也行，官方还提供了一个 React 版本的示例套件。但我的建议是按需安装分包，这样能更清楚自己的能力边界，日后做定制也能快速定位问题。

3.2 从初始化到渲染出第一份工作簿

先给一个最简可用的示例：

import { Univer } from '@univerjs/core'; import { defaultTheme } from '@univerjs/design'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'; import { UniverFormulaEnginePlugin } from '@univerjs/sheets-formula'; const univer = new Univer(); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsUIPlugin, { container: 'app', }); univer.registerPlugin(UniverFormulaEnginePlugin);

再给一份演示数据：

const workbook = { id: 'workbook-demo-001', sheets: [ { id: 'sheet-001', name: '月度销售', cellData: { '0,0': { v: '品类' }, '0,1': { v: '一月' }, '0,2': { v: '二月' }, '1,0': { v: '果茶' }, '1,1': { v: 1200 }, '1,2': { v: 1500 }, '2,0': { v: '奶茶' }, '2,1': { v: 2000 }, '2,2': { v: 1800 }, '3,0': { v: '合计' }, '3,1': { v: '=SUM(B2:B3)' }, '3,2': { v: '=SUM(C2:C3)' }, }, }, ], }; univer.createUniverSheet(workbook);

把这段逻辑放到组件的onMounted生命周期里，一打开页面就能看到一个可编辑的工作簿，并且合计行已经能够通过公式引擎自动计算出结果。这里cellData的 key 是行号,列号字符串，行和列都从 0 开始；v字段表示单元格的原始值，公式也写在v里，以=开头。

3.3 样式和交互的常用配置

光能看能编辑还不够，实际业务中一般还需要改单元格样式、设置列宽行高、冻结窗格这些。univer 里调整样式最直接的方式就是构造一个“命令”，让所有操作走统一链路。例如设置选中区域背景色：

univer.getCurrentUniverSheetInstance().getCommandService().executeCommand({ id: 'sheet.command.set-range-style', params: { range: { startRow: 0, startColumn: 0, endRow: 3, endColumn: 2, }, style: { backgroundColor: '#f5f5f5', fontStyle: 'italic', }, }, });

除了命令方式，部分 UI 操作也可以通过 API 直接完成，比如设置当前活动 Sheet、跳转到指定单元格。实际写业务的时候，我更推荐在命令基础上再包一层业务服务，方便以后增加日志埋点、权限判断或者自定义撤销规则。

4. 公式联动、数据校验和撤销重做的坑

跑通基础 Demo 只是开始。在真实项目里，你需要处理很多“看起来应该很简单，真做起来容易走弯路”的场景。下面按我自己踩过坑的优先级讲。

4.1 自定义公式函数的设计思路

univer 的公式引擎和 Excel 的套路类似，如果你需要一套业务上的特殊计算，比如根据订单状态自动返算佣金，最正确的做法是注册一个自定义函数，而不是在前端拿到公式字符串后放飞式地处理。

自定义公式的注册很简单：

import { FunctionType, FunctionBase } from '@univerjs/sheets-formula'; class CommissionFunction extends FunctionBase { name = 'COMMISSION'; type = FunctionType.NORMAL; calculate(value: number, rate: number): number { return value * rate; } }

注册后即可在单元格里写=COMMISSION(A2, 0.15)。这个能力非常实用，尤其是当业务规则经常变的时候，把计算逻辑收敛到公式函数里，能让最终生成的文档在导出或协作时保持一致。

不过注意一个细节：自定义函数最好按照“纯函数”的规范去写——不要把外部异步请求直接放在公式计算里。因为公式引擎会在各种时机触发重算，你要是依赖一个可变的全局状态，计算结果就可能飘忽不定。如果非要去数据库里取数，建议提前把数据快照加载到当前上下文，再在公式里引用。

4.2 数据校验的弹窗逻辑与提交时机

univer 支持在单元格上设置数据校验规则，比如下拉列表、数值范围、文本长度等。依赖项是@univerjs/sheets-data-validation这个插件。

数据校验在界面上表现为：用户点击单元格，会触发一个校验器；校验不通过时展示警告或阻止输入。集成时最容易踩的坑是“校验时机”的判断。如果你在onChange阶段就立刻触发校验，用户可能只是路过一个单元格还没输完，弹窗就已经跳出来了，体验非常糟。更好的做法是监听单元格编辑提交事件，再触发校验，并把错误信息展示到自己的业务 UI 上。

另外，借用 univer 的校验机制时千万别只把它当 UI 验证。底层导出或提交给后端的数据，必须再校验一遍。因为绕过 UI 直接改数据模型是可以做到的事情，你不能假设所有数据都来自编辑器交互。

4.3 撤销重做：范围与粒度由你自己决定

univer 的撤销重做不是简单的快照对比。它记录的是命令执行序列，所以你要想清楚：哪些操作应该进入撤销栈，哪些不用。例如程序自动批量给一串单元格赋默认值，这种后台操作一般不应该被用户撤销；而用户在工具栏点一个“填充颜色”，则非常应该进入撤销栈。

一个实用策略是：所有来自用户交互的操作，统一走命令系统并纳入撤销栈；来自业务初始化、代码逻辑和协作同步的操作，通过直写数据模型或使用可忽略的标记来执行。这样既能保留“撤销上一个用户操作”的能力，又不会把程序行为和历史记录搅在一起。

另外一个非常容易踩的点是：撤销重做不一定覆盖外部自定义插件创建的 UI 操作。比如你写了一个侧边栏配置面板，它是独立 React 组件，你改了控件值之后如果希望通过 univer 工具栏的“撤销”来恢复，就必须在代码里主动发送对应命令并监听撤销事件。否则用户点撤销，只会看到表格内容回滚，但你的侧边栏配置不会跟着变化，一旦表格重新渲染，你以为的“配置”可能还在，但文档数据已经不是当时的状态了。

5. 协作与多实例通信的关键细节

univer 最吸引人的一点，是它从底层把协同编辑作为一等公民来设计。不过并不是接上官方渠道就万事大吉，你要关注数据同步和冲突处理的几个细节。

5.1 协同服务的职责边界

协同场景中，univer 本身可以只当一个纯前端编辑器，网络同步逻辑由业务后端负责。核心思路是：前端把每次操作转换成命令，再把命令上传给服务端；服务端负责合并命令、按序分发给其他在线用户；前端收到远程命令后，在本地重新执行一遍，更新数据模型。

因此你需要关心的不是 univer 内部如何冲突合并，而是前后端的传输协议与命令格式。univer 官网文档里关于协作的部分提供了一套参考 WebSocket 通道设计，但真正落到生产环境，还要考虑心跳、断线重连、命令幂等性和版本号对齐。我的建议是，初期不要直接架设完整协同服务，先用一个简单的广播通道让两个浏览器标签页之间互发命令，比对一下客户端状态是否保持一致，再逐步加入冲突策略。

5.2 命令的幂等性与客户端状态对齐

多端同步最容易翻车的，不是网速，而是命令丢失或重复执行后导致数据不一致。比如用户 A 设置 A1 单元格为红色，用户 B 同时把 A1 的值改成 100。这两条命令在网络传输中可能发生顺序上的重排。univer 是本地即时执行，重复执行同一条命令时，如果命令实现不保证幂等，单元格值就可能被覆盖两次。

实践中建议：每条命令加上全局自增序列号，服务端按序列号排序后再分发给所有端，客户端严格按序执行。切忌在客户端本地直接改数据而不生成命令，因为一旦这种行为进入协同环境，其他端根本不知道发生了什么，冲突无可避免。

5.3 权限控制与只读模式

如果你的业务里需要一部分用户只能看不能改，univer 里可以通过设置 Workbook 或特定 Sheet 的权限状态来达成。简单的做法是禁用指定命令，例如对只读用户不注册 Sheet 编辑类的命令或在使用方判断权限后直接拦截。更细粒度的做法是实现在线文档常见的“单元格锁定”——锁定区域内不能编辑，但允许选择和查看公式。

这里需要特别注意一个“明暗”搭配的问题：只做前端拦截是不够的。后端在接收命令时也必须校验权限，否则一个懂点前端的人完全可以直接构造命令请求绕过 UI。所以权限的本质是后端校验，前端只负责体验优化。

6. 从 Demo 到生产环境：性能、定制和常见翻车现场

集成 Demo 只是入门，真正把 univer 用进生产线，你需要花时间处理性能和定制问题。这部分把我在实际项目中遇到的高频问题集中说一下。

6.1 大数据量渲染与滚动

表格组件最怕的从来不是数据多，而是一次性渲染的数据节点多。univer 的 Canvas 渲染策略让它天然比 DOM 方案更适合处理大数据量。我实测过在一个 Sheet 里放 5 万行、每行 20 列数据，初始渲染和滚动都还算流畅。但如果你同时打开多个 Sheet，并且每个都塞大量数据，初始化时间还是会变长。

要优化，首先应避免在初始化时一次性塞入完整数据，而是先加载当前可视区域附近的必要数据，等滚动到新的区域再动态请求或生成。univer 的数据模型允许按需填充cellData，不需要把所有空白单元格都写进去。其次，公式数量也要控制。如果每个单元格都挂着一个复杂的数组公式，算力开销会成倍增长，建议能用静态值缓存的地方，就不要全部依赖公式实时重算。

6.2 样式隔离与多主题的坑

univer 自带一套默认主题，引入时还会加载一组 CSS 变量。如果项目本身有大量全局样式，容易出现样式互相覆盖。自己项目的reset.css可能把 univer 内部组件的box-sizing改掉，导致排版错位；univer 的主题色变量也可能溅到你自研的业务组件上。

一个比较稳的做法是：

• 给 univer 的挂载容器设置独立的命名空间，例如<div id="univer-container">；
• 对落地页样式采用针对性选择器，避免全局* {}规则失控；
• 如果要换主题，在初始化时传入自定义主题变量，而不是事后用 CSS 硬覆盖。

另外，univer 官方 UI 层的消息提示、右键菜单、弹窗默认是直接挂在 body 底层的，这样在弹窗内的单击事件有时候会被外层业务逻辑捕获。若项目里有全局点击监听器，建议在事件处理中用contains判断目标是否来自 univer 容器，再做逻辑分支。

6.3 项目里最常见的几个翻车现场

我把这一两年的问题排查经验归纳一下，先讲一个典型的：挂在 React 组件里反复执行初始化导致的“重复实例”问题。univer 对象在创建之后，会把工作簿注册到自己的实例池中。一旦组件的useEffect因为热更新或依赖变化重复执行，而你没有清理旧实例，就可能出现两个 univer 实例同时监听同一容器的事件，导致编辑错乱、命令重复执行。正确的做法是在useEffect的清理回调里调用univer.dispose()，并把初始化逻辑做成幂等操作。

另一个常见问题是初始化时机和容器尺寸。如果你在容器还没渲染出实际宽度高度的时候执行createUniverSheet，univer 计算的视口大小会不准确，表格区域可能出现空白或滚动错位。在 SPA 项目里尤其常见——路由切换后组件蒙层还在加载，初始化脚本却已经跑完了。解决方案是等目标容器offsetWidth > 0再执行初始化，或者监听容器尺寸变化后主动触发一次重绘。

还有一个很多人不注意的是公式中的中英文符号和数字格式。用户从 Excel 复制表格内容粘贴进 univer 时，可能带着各种富文本格式、图片和跨 Sheet 引用。如果粘贴的内容里含有非标准函数名称或错误的分隔符，univer 会返回解析错误。针对这类问题，建议在粘贴后增加一层“清洗”逻辑，把纯文本数据和公式内容分开处理，并且用官方提的 API 来批量写入单元格，而不是直接扫描剪贴板文本去猜。

6.4 按需加载与产物体积控制

univer 作为一个功能丰富的办公套件，整体体积不小。如果你不做任何调优，首屏包会明显增大。好在它的分包做得比较清楚，你可以：

• 只引入当前业务需要的模块，例如不需要文档和幻灯片时，就别引入对应插件；
• 代码层面采用动态引入，在用户真正打开报表页时才加载表格相关模块；
• 对于自定义业务面板，尽量抽成独立懒加载组件，不要一股脑放进主包。

根据我的实测，一个只有基础表格、公式和数据校验能力的项目，在按需加载后，gzip 后的体积能控制在合理范围，相比直接引入全家桶要节省很多。

7. 进阶玩法：把 univer 嵌入自定义工作流里

基础能力到位之后，你就可以开始考虑怎么让它深度融入自己的产品了。很多人只会把 univer 当做一个与业务剥离的“编辑控件”，但其实它的插件化能力能让它变成业务流程里非常顺滑的一环。

7.1 自定义工具栏与业务模板

比如你的产品里需要一套“项目周报”模板，包含固定的表头、计算公式和数据校验规则。你不用每次让用户手工录入，而是初始化时加载一套外部预设模板数据，并配合权限设置，让用户只能编辑特定区域。这件事用 univer 做起来很舒服：

• 模板数据以 JSON 形式维护，随时下发；
• 对固定区域设置单元格锁区和保护；
• 自定义一个“一键填充上周数据”按钮，通过命令写入历史数据。

这套流程落地后，用户不需要关心 Excel 文件在哪、字段怎么命名，打开网页就是一张结构清晰、校验完整的业务表格。

7.2 与后端文档结构同步

univer 的数据不是只能用它的私有格式。你可以监听文档变更事件，把编辑后的结构转换为业务自己的 JSON 或直接生成标准文件格式再提交服务端。这里建议用快照 + 增量命令双轨机制：服务端可以定期存储整个文档快照作为恢复点，同时保存期间的增量命令用于微小变更的还原。这样做既能降低存储压力，又能满足历史版本回滚的需求。

一个更实体化的方案是：把 univer 的持久化数据存放在对象存储里，每次变更只提交命令日志，服务端通过消息队列异步将命令转换为快照。这样前端几乎不需要等待后端响应，用户体验非常顺滑。

7.3 跨模块数据联动

如果你的产品里有多个文档模块，比如一个 PDF 预览区、一个数据分析看板、一个在线表格编辑区，univer 可以成为承载数据处理的核心模块。编辑表格后，通过事件机制把最新的单元格数据广播给其他模块刷新图表，反向也一样：外部筛选条件变化时，用命令切到对应 Sheet 并更新视图。真正做到“一处编辑、处处响应”。

这种联动如果不用命令系统，非常容易出现状态错乱。因为各方只关心自己看到的 UI，谁都不会为“共享数据状态”负责。而 univer 的命令系统天然就是为这种多端同步而生的，你用着用着会发现，用它来串业务状态，比自己在外面维护一份全局 Store 要省心得多。

8. 合上电脑前的几句话

如果只让我总结一句话：univer 最大的价值不是“又一个在线表格组件”，而是它把“表格引擎”和“UI 外壳”解耦了，让开发者能按需拼装，同时也给协作和复杂业务留好了足够的扩展位。

我在实际项目里的体会是，刚上手时别急着把所有插件都装上，也别一上来就搞协同、搞自定义工具栏。先把一个基础的编辑场景跑通，理清楚命令、数据模型和渲染三者之间的关系，再去慢慢加功能，遇到问题时会轻松很多。还有一个小技巧，多去翻它的官方源码示例，尤其是那些不带 UI 的纯命令示例，很多你原本以为要靠 hack 才能解决的问题，在它的源码里都有对应答案。

希望这篇分享能给你提供一份相对完整的上手地图。接下来留给你自己去动手试一试，把 univer 放到你的业务场景里，相信你会发现更多值得挖掘的能力。