企业官网建设流程全解析

这两年如果一直在跟前端开源圈子，大概率已经在关注列表里见过univer这个名字。它不是一个花架子组件库，而是一个用 TypeScript 重写的、把电子表格、文档和幻灯片能力打包到一起的 Web 办公套件内核。我第一次把它接进内部低代码平台时，第一反应是：这个项目怎么把 Excel 级别的交互做在 Canvas 上，而且还能让我不怎么看源码就插一个自定义按钮。搞清楚这套东西的前后，我也踩了不少坑，这篇就当作一份踩坑后的梳理。如果你需要在自己的系统里加表格能力，或者想把报表、审批表、在线录入表单统一起来，这篇文章会比较对胃口。

1. 先搞清楚 Univer 到底解决什么问题

1.1 它不是一个单纯的 Excel 克隆

很多人在 GitHub 上看到 univer 的第一眼，会下意识把它归类为"又一款在线表格组件"。这个理解不能说错，但会把它的价值看小很多。Univer 的定位是办公文档的现代化基础平台，而不是"页面里嵌一个表格控件"。

它本身包含三类文档能力：Sheet 表格、Doc 文档、Slide 演示稿。无论你激活哪种文件类型，它都跑在同一套插件体系上，数据模型、渲染引擎、公式引擎、UI 框架是共用的。这点和传统库完全不同——传统表格库是"一个独立组件，做好表格就算完事"，Univer 更像是"把 Office 的核心骨架复刻到前端运行时里，你需要什么能力就装什么模块"。

那它到底解决了什么？我自己的理解是三个层面：

• 业务层面：很多系统都需要在线录入、批量编辑、类 Excel 的交互，Univer 直接给了完整能力，不用从零造轮子。
• 定制层面：改菜单、加按钮、挂右键操作、监听单元格变动、接后端实时数据，都有清晰的扩展点。二次开发不需要改动它的内部源码。
• 生态层面：一个活跃维护的开源项目，社区插件和示例在不断增加，比维护一个自研表格引擎省心得多。

所以，如果你是前端工程师，要在低代码平台或企业内部系统里做表格模块；如果你是项目负责人，正在选型在线编辑方案；甚至你是做数据可视化、报表设计器的开发者——Univer 都值得认真评估。

1.2 和你熟悉的几个方案横向对比

没有对比就谈不上选择。我列几个常见方案，都是我自己接触过或在社区里被经常横向比较的：

简单说，Luckysheet 这类老牌组件胜在"开箱即用"，但它们本质上是一张"静态表单"，深度定制时往往要改内部逻辑；OnlyOffice 又太重，不适合只想要一个表格模块的场景。Univer 正好处在中间：组件级嵌入的轻量，加上可扩展的内核架构。它把"文档数据层"和"UI 渲染层"分开，你在上层的自由度比传统表格库高不少。

2. 架构拆解：Univer 的"插件化 + 多文档内核"是怎么运作的

2.1 核心包有哪些，各自管什么

用 npm 安装 Univer 时，你会发现它不是一个大包，而是一堆@univerjs/*的子包。这是它最核心的设计：模块化。我已经写过的核心包大概有：

• @univerjs/core：核心框架，负责插件注册、命令分发、文档生命周期管理。
• @univerjs/sheets：表格业务逻辑，不依赖 UI，处理单元格、行列、选区等数据。
• @univerjs/sheets-ui：表格的 UI 层，把数据和工具栏、右键菜单、选区交互连接起来。
• @univerjs/ui：通用 UI 基础设施，比如布局、弹窗、菜单的渲染。
• @univerjs/engine-render：Canvas 渲染引擎，负责把表格画出来。
• @univerjs/engine-formula：公式计算引擎。
• @univerjs/engine-numfmt：数字格式处理。

你可以只注册渲染引擎和表格插件，得到一个纯展示的表格；也可以再加上公式引擎、UI 插件，变成一个完整编辑器。依赖关系是单向的、清晰的：core 是地基，sheet 和 doc 是业务模块，render 是出口，ui 是交互层。这种分层让我在排查问题时非常舒服——公式算错我去看 formula 引擎相关逻辑，渲染问题我去看 render 相关配置，不会在一堆代码里找不着北。

2.2 命令系统：一切操作都是命令

Univer 内部有一套命令系统，这是它和普通表格组件最大的区别之一。在传统组件里，你要改一个单元格的值，通常是调用组件的 setValue 方法；但在 Univer 里，每一次用户操作——输入、删除、合并单元格、设置样式——都会被封装成一个命令（Command）。

这个设计有点像遥控器：你按下"音量+"，遥控器发出一个按键信号，电视内部再去决定怎么放大声音。Univer 的命令系统天然附带两个好处：

• Undo/Redo 好做：只要把命令执行前后的状态变化记录成可逆操作，撤销就可以统一处理。Univer 在这块做得很完整，你不需要为了撤销功能自己打补丁。
• 业务逻辑和 UI 彻底解耦：前端按钮点击后只是分发一个命令，真正干活的是命令处理器。这样命令可以被工具条触发、被快捷键触发、被脚本触发、甚至被协同端的远程消息触发，行为完全一致。

我自己做二次开发时，经常就是"注册自己的命令 + 在 UI 里加一个入口"，整个过程对原有逻辑零侵入。

2.3 渲染引擎：为什么复杂的表格也能拖得动

Univer 的渲染层不走 DOM 节点，而是用 Canvas 绘制。每个单元格、每个网格、每个浮层，最终都画在一个画布上。这就是为什么它能渲染几十万甚至上百万格子的表格，而浏览器的 DOM 早就卡死的情况。

这个渲染引擎有几个关键概念：Scene是场景，Viewport是视口，Layer是图层，Object是画布上的对象。滚动、缩放、选区高亮都是在这个引擎里完成的。我不需要一上来就懂到这么深，但理解"它不是为单个单元格挂 DOM 事件，而是整块画布在持续重绘"这一层，能帮你避开很多性能坑。

提示：如果在表格上叠加自定义的浮层或按钮，不要直接在画布区域塞一个思忖元素就完事，最好按官方的渲染对象机制挂到 Layer 上，否则滚动时浮层位置对不齐。

3. 从零开始：5 分钟跑起一个最小 Univer 实例

3.1 工程初始化

先准备一个空的前端工程。我通常习惯用 Vite + TypeScript 起步，因为 Univer 本身就是 TS 写的，类型提示舒服很多。

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

然后安装 Univer 相关依赖。不同大版本的包名会有差异，我这里以当前比较常见的 0.x 版本写法为例，安装时建议直接查一下官方文档的"快速开始"确定最新包名：

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

顺手把设计主题的样式引进来，这一步很多人会漏：

import '@univerjs/design/lib/index.css'; import '@univerjs/sheets-ui/lib/index.css';

忽略样式文件的结果就是界面画得乱七八糟，所有组件都像没穿衣服。这里算第一个容易踩的坑。

3.2 初始化 Univer 与注册插件

在main.ts里创建一个最简实例。核心代码大致长这样：

import { Univer } from '@univerjs/core'; import { defaultTheme } from '@univerjs/design'; import { UniverUIPlugin } from '@univerjs/ui'; import { UniverRenderEnginePlugin } from '@univerjs/engine-render'; import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'; import { UniverSheetsPlugin } from '@univerjs/sheets'; import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'; const univer = new Univer({ theme: defaultTheme, locale: 'zhCN', }); univer.registerPlugin(UniverRenderEnginePlugin); univer.registerPlugin(UniverFormulaEnginePlugin); univer.registerPlugin(UniverUIPlugin, { container: 'app', toolbar: true, }); univer.registerPlugin(UniverSheetsPlugin); univer.registerPlugin(UniverSheetsUIPlugin);

注意注册顺序，一般建议先把渲染引擎和公式引擎注册好，再注册 UI 和表格插件。插件之间如果顺序不对，某些依赖关系没准备好，会在控制台报错。这个顺序是官方示例和社区里比较标准的写法。

3.3 创建第一个工作表单元

注册完插件，还需要创建一个具体的文档单元。Univer 里一个表格文件就是一个Unit，通过createUnit创建：

univer.createUnit(UniverSheetsPlugin, { name: '第一个表格', sheetOrder: ['sheet1'], sheets: { sheet1: { name: 'Sheet1', rowCount: 100, colCount: 26, cellData: { 0: { 0: { v: '你好 Univer', s: { b: true, cl: { rgb: '#FF0000' } } } } } } } });

这里cellData的格式是行号 -> 列号 -> 单元格对象，行号列号从 0 开始，v是显示值，s是样式描述。比如{ b: true }表示加粗，{ cl: { rgb: '#FF0000' } }表示红色字体。

启动开发服务器：

npm run dev

浏览器打开后，你就能看到带工具栏的一个在线表格，A1 单元格里写着红色的"你好 Univer"。从安装到跑起来，确实也就几分钟。

4. 让表格真正能用：公式、跳过区、格式与数据交互

4.1 公式引擎：从选配到必备

我最早试用 Univer 时，把UniverFormulaEnginePlugin注册漏了，结果在单元格里输入=SUM(1,2)后，单元格只显示公式文本，不计算结果。查了半小时才反应过来是公式引擎没装。

公式引擎在 Univer 里是一个相对独立的模块。注册后，你可以直接在单元格里输入公式，也可以用代码写入公式字符串：

// 通过 univerAPI 给 B2 写入求和公式 const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook.getActiveSheet(); sheet.getRange(1, 1).setFormula('=SUM(A1:A10)');

关于univerAPI：这是 Univer 对外暴露的一个全局 API，在浏览器控制台和在业务代码里都可以拿到。它像是一个官方留下的"后门"，很多运行时操作可以通过它完成，是二次开发里非常顺手的一个入口。

公式引擎本身的计算是在内部异步执行的，大表格场景下不会阻塞 UI 渲染。性能上，Univer 团队把公式计算放到了独立的引擎里，整体思路接近专业表格软件的做法。

4.2 不烧脑的样式与数据验证

Univer 的 UI 层已经把常规功能都集成进去了：字体、字号、背景色、边框、合并单元格、条件格式、数据验证、筛选、排序等等。这些在工具栏上点就行，不需要写代码。

如果需要编程式设置样式，可以这样用：

const range = sheet.getRange(0, 0, 5, 5); // A1:E5 range.setBackgroundColor('#F5F5F5'); range.setFontWeight('bold');

对比一下以前用老表格组件时，动不动就要操作innerHTML或者手动维护一套样式映射，Univer 的 API 设计明显更符合开发直觉。它把选区模型封装得很好，getRange(startRow, startCol, endRow, endCol)一次定位一个区域，后面接各种 set 方法就行。

数据验证（比如单元格只能选"是/否"、只能输入数字范围）也内置了，从sheets-ui的菜单里可以配置，也可以通过命令动态设置。这个能力在业务系统里特别实用——审批表里的下拉选择、填报系统里的数字范围限制，基本都属于这一类需求。

4.3 Excel 文件怎么导入导出

导入导出是很多业务系统的硬需求。Univer 官方有配套的导入导出插件，但由于项目迭代快，包名在不同版本有变化。我目前配合下来的稳妥方案是：

• 用 SheetJS（xlsx库）解析 Excel 文件，拿到单元格矩阵；
• 再把单元格数据组装成 Univer 的cellData结构，通过命令一次性写入 Univer；
• 导出时反过来，取 Univer 的单元格数据，组装成 SheetJS 的 WorkBook，再调用writeFile下载。

这么做的好处是，即使 Univer 自己的导入导出包升级换代，我的系统底层仍然是稳定的一层数据结构映射，不会因为上游 API 变化就崩掉。如果项目的版本侧比较新，也可以直接看官方文档用官方插件，原理是一样的。

4.4 编程式操作与事件监听

Univer 允许你完全绕开界面，用 API 操作表格数据。我自己的经验是：在初始化时尽量通过数据一次性渲染，运行过程中通过 API 精准修改，而不是每次更新都重新创建 Unit。

常用操作可以归个类：

监听这块尤其重要。你在做联动逻辑时（比如 A 单元格改了，B 单元格要自动变），必须要有一个可靠的"数据变化"信号。Univer 的事件机制做得还挺清晰，找到对应文档照葫芦画瓢即可。

5. 二次开发：写你自己的第一个 Univer 插件

5.1 插件的基本构成

如果你只是需要表格功能，不写插件完全没问题。但一旦想加自定义按钮、自定义右键菜单、自动填充规则、业务快捷键，插件机制才是正经路子。

一个插件本质上是继承Plugin的子类：

import { Plugin, PluginType } from '@univerjs/core'; export class MyBusinessPlugin extends Plugin { static override type = PluginType.Sheet; constructor() { super('my-business-plugin'); } override onStarting(): void { // 初始化依赖，可以注册命令 console.log('插件开始启动'); } override onReady(): void { // 启动完成后执行，可以操作文档 console.log('插件已就绪'); } }

然后在初始化时univer.registerPlugin(MyBusinessPlugin)即可。生命周期方法里，onStarting适合注册命令、监听事件，onReady适合执行首轮同步逻辑。这只是个模板，真正复杂的功能都是在这个框架里逐步加进去的。

5.2 注册一条自己的命令

之前说过 Univer 的一切操作都是命令。自定义命令也很简单，核心是定义CommandType.OPERATION或CommandType.COMMAND类型的 ID，然后注册相应 handler。大致结构：

import { CommandType, ICommand } from '@univerjs/core'; interface IMyCommandParams { sheetId: string; startRow: number; endRow: number; } export const myCommand: ICommand<IMyCommandParams> = { id: 'my.command.fill-serial', type: CommandType.COMMAND, handler: async (context, params) => { // 在这里写业务逻辑 return true; }, };

handler返回true表示执行成功，返回false就会被视为失败。这样可以被undo机制正确调用。你还可以配套注册可逆操作，让用户能撤销你的插件行为。

5.3 实战示例：一键填充序号

这里我写一个小而完整的案例：在工具栏加一个按钮，点击后把当前选区第一列填充为 1 到 N 的序号，并把字体设为加粗。这也是我在内部系统里经常用到的一个真实场景。

先定义命令：

export const fillSerialCommand: ICommand = { id: 'demo.command.fill-serial', type: CommandType.COMMAND, handler: async (context, params) => { const workbook = univerAPI.getActiveWorkbook(); const sheet = workbook.getActiveSheet(); const selection = sheet.getSelection(); // 获取当前选区 if (!selection) return false; const { startRow, endRow, startCol } = selection; const data = Array.from({ length: endRow - startRow + 1 }, (_, i) => [ undefined, ...[], ]); // 这里为了演示，直接按行填充到 startCol 列 for (let i = startRow; i <= endRow; i++) { sheet.getRange(i, startCol).setValue(i - startRow + 1); sheet.getRange(i, startCol).setFontWeight('bold'); } return true; }, };

再把按钮塞到工具栏。按钮入口的注册方式在不同版本有差异，有的是通过 UI 插件配置customMenus，有的是直接在自己插件的onReady里调用工具条 API。思路是一致的：新增一个 UI 入口，点击后分发命令。

这个示例本身逻辑很简单，但它演示了二次开发的完整链路：命令定义 -> handler 实现 -> UI 入口绑定。链路一旦打通，后面做任何业务功能都可复用。

6. 常见问题、性能心法与版本选择

6.1 版本黑洞：0.x 到 1.x 的破坏性迁移

这是使用 Univer 过程中必须接受的一件事：它的版本迭代速度很快，很多 API 在次要版本之间都可能改名。你查一下社区，基本每个人都会遇到"升级后插件全部报错"的问题。

我自己的做法是严格锁版本：

{ "dependencies": { "@univerjs/core": "0.2.9", "@univerjs/sheets": "0.2.9" } }

没有十足的必要，不轻易升小版本。看文档时也只看对应版本号的文档，不要拿最新版文档去对旧版本代码。等一个大版本稳定后，再统一规划迁移。

我把踩过的坑整理成了速查表，方便你排查时一眼定位：

6.2 性能优化：大表格场景的几个心法

Univer 的 Canvas 渲染已经解决了一大部分性能问题，但如果你要做的是"大数据量报表"，还是有些细节需要注意：

• 初始化时一次性传数据，不要初始化后再循环几千次 setValue。前者走的是批量渲染通道，后者每一次都会触发重算，性能差一个量级。
• 善用选区批量操作，例如getRange(0, 0, 499, 9)一次性设置 500 行区域的样式，而不是逐行设。
• 公式别写整列，像=SUM(A:A)这种对整列的计算在数据量大时非常考验引擎，建议限定到实际使用区域。
• 关闭不需要的插件。如果你只用表格和公式，就不要注册演示文稿和文档相关的插件，减少启动时的初始化开销。

这些经验不是文档上写的，是我在一个真实项目里反复压测才得出的。有一段时间每操作一次就要等一两秒，后来发现就是初始化后逐格更新数据导致的，改完后顺畅多了。

6.3 关于 Univer Server 与协同能力

最后一件事需要心里有数：Univer 的开源版本身提供了非常完整的前端编辑能力，但多人实时协同、后端保存、权限管理这些能力是围绕 Univer Server 和配套服务设计的。如果你要做的是单机编辑或简单的单用户录入，那开源版就够了；如果是多用户实时协同的 SaaS 产品，就要考虑服务端部署和商业授权。

我见过不少人拿开源版直接上生产，也没有任何问题，前提是业务不依赖多人协同。如果你只是企业内部工具，把数据通过你自己的接口保存，前端用 Univer 渲染编辑，这条路完全走得通，甚至可以说性价比极高。

一点个人体会

我实际使用 Univer 做项目后最大的感受是：它的确是有长期主义设计的项目，值得为它花时间学习，但也正因为还在快速成长期，你必须把版本治理当成正经事来抓。不要一上来就追求最新版，而是先确认自己的业务场景和它当前稳定版本的能力边界。

如果让我给后来者一句建议，那就是：小步快跑，先用一个最小的 Sheet 跑通业务闭环，再逐步加公式、样式、插件和事件联动。Univer 最舒服的地方在于它的扩展方式非常结构化，你不需要在"又要加一个功能"时推倒重来。它不是一个用完即弃的组件，而是一个能陪你迭代好几代业务系统的底座。