ARTICLE · 1369860
把开源 Excel 嵌进你的产品:Univer 上手实录
01Univer 是什么
Univer 是 dream-num 团队开源的 Office SDK,定位是「把 Office 编辑、公式计算、协同和文件处理能力装进你自己的产品」。表格、文档、演示文稿这些能力不再是独立应用,而是可以嵌进任意 Web 页面的组件。
它把产品拆成三层:Web SDK 负责内容模型、编辑渲染和公式引擎,核心架构以 Apache-2.0 开源;Server SDK 提供实时协同、编辑历史和文件导入导出;AI SDK 把这些 Office 能力接给现有的 Agent 和工作流。开源仓库里跑通一切的是 Web SDK 的 Sheets 和 Docs 编辑能力。
以下数据核对于 2026 年 11 月 16 日:GitHub 上 26,714 star、2,431 fork,主语言 TypeScript,协议 Apache-2.0(商用插件与 Server SDK 单独授权),当天在 Trending 榜上升 988 星排第一。
仓库有 6,051 次 commit、159 个 tag,最新版本 v1.5.2,npm 上 @univerjs/preset-sheets-core 同日刚发过版——活跃度肉眼可见。
02为什么值得前端学
第一,它把「表格」这个前端最难啃的轮子变成了依赖。自己实现选区、合并单元格、富文本、撤销重做和公式依赖图,没有一年下不来;Univer 把这些做成了插件化的 Preset,npm i 之后十几行代码就能渲染出一个完整编辑器。
第二,Facade API 天然为「程序操作」设计。编辑器里人能做的事,代码同样能做:填数据、改单元格、读公式结果、存快照。这意味着它不只是 UI 组件,还是 AI Agent 操作表格的执行层——官方那句「给人和 Agent 用的同一套 API」不是我转述的,是 README 原文。
第三,公式引擎独立于渲染存在,可以做无头计算。业务系统里「填一张带公式的记录表然后取合计」这种需求,用它在浏览器端就能完成,不依赖任何服务端。
03十分钟上手:从空目录到完整编辑器
先建项目。我本机是 Node 22.22.2,全程用 npm,137 个包装完约一分钟:
mkdir univer-demo && cd univer-demonpm init -ynpm i @univerjs/presets \ @univerjs/preset-sheets-corenpm i -D vite typescript在 package.json 里加一个 dev 脚本:
{ "scripts": { "dev": "vite" }}然后准备一个撑满视口的容器,Univer 会把整个编辑器渲染进这个 div:
<body> <div id="app" style="height: 100vh"></div></body>核心是这段初始化代码。注意 locale 和 locales 必须同时给,不传中文包界面也能出,但顶部工具栏会直接报错(这个坑后面细说):
import { createUniver, LocaleType, mergeLocales,} from '@univerjs/presets'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'await import( '@univerjs/preset-sheets-core' + '/lib/index.css')const ZHCN = (await import( '@univerjs/preset-sheets-core' + '/locales/zh-CN' )).defaultconst { univerAPI } = createUniver({ locale: LocaleType.ZH_CN, locales: { [LocaleType.ZH_CN]: mergeLocales(ZHCN), }, presets: [ UniverSheetsCorePreset({ container: 'app', }), ],})univerAPI.createWorkbook({})npm run dev 起服务,浏览器打开就有一个完整的电子表格编辑器——工具栏、公式栏、行号列标、缩放控制一应俱全。我本机真实输出如下:
$ npm run dev VITE v7.3.8 ready in 312 ms ➜ Local: http://localhost:5273/
04填一份会算账的报价单
编辑器只是壳,价值在 Facade API。getActiveWorkbook 拿到工作簿,getRange 拿到任意区域,setValues 一次写入。公式和普通文本写法完全一样,= 开头引擎就认:
const sheet = univerAPI.getActiveWorkbook() .getActiveSheet()sheet.getRange('A1:D4').setValues([ ['商品', '数量', '单价', '小计'], ['会议座椅', 2, 25, '=B2*C2'], ['技术支持', 1, 100, '=B3*C3'], ['合计', '', '', '=SUM(D2:D3)'],])await univerAPI.getFormula() .onCalculationResultApplied()console.log('D4 =', sheet.getRange('D4').getValue())onCalculationResultApplied 返回一个 Promise,公式引擎算完才 resolve——这是取「最终结果」的可靠时机。用脚本读取 D4 单元格,真实输出:
$ node demo-run.mjsformula engine readyD4 (SUM) = 150set B2 = 4, D4 = 200undo -> B2 = 2workbook.save() -> 1420 chars两行座椅乘单价 50,一行技术支持 100,SUM 合计 150,分毫不差。上面终端输出里的每一行都来自我本机的真实运行,后三行是下一步的实测预告。

05让程序替人操作表格
接下来是整篇文章我最想强调的能力:代码改一个单元格,公式引擎自动重算全表。把 B2 从 2 改成 4,什么都不用做,D4 自己变成 200:
const api = window.univerAPIconst sheet = api.getActiveWorkbook() .getActiveSheet()sheet.getRange('B2').setValue(4)await api.getFormula() .onCalculationResultApplied()console.log( sheet.getRange('D4').getValue())// 200这就是「给人和 Agent 同一套 API」的含义:编辑器里敲键盘,和代码里 setValue,走的是同一条命令通道。AI Agent 拿着这套 API 就能直接操作表格,不需要模拟点击。
顺手测了撤销和快照:undo() 把 B2 退回 2,workbook.save() 返回整个工作簿的 JSON 快照,实测 1,420 个字符,全部发生在浏览器端。

06快照持久化:数据归你的应用管
Univer 不替你存数据。save() 返回的快照是普通 JSON,存 localStorage、发后端、落数据库都随你;下次加载时把它传回 createWorkbook 就能原地恢复。我的快照实测长这样:
下面是从我本机真实快照里节选的骨架(完整快照 153 行):
{ "id": "Mlq4l6", "name": "", "appVersion": "1.5.2", "locale": "zhCN", "sheets": { "5HbhSSaHBHkI7nM8yYU1x": { "id": "5HbhSSaHBHkI7nM8yYU1x", "name": "Sheet1", "rowCount": 1000, "columnCount": 20, "zoomRatio": 1, "defaultColumnWidth": 88 } }}const snap = workbook.save()localStorage.setItem( 'quotation', JSON.stringify(snap))// 下次加载:恢复而非新建const saved = localStorage.getItem('quotation')if (saved) { univerAPI.createWorkbook( JSON.parse(saved) )}这个设计对业务系统很友好:持久化方案跟着你的技术栈走,Univer 只负责编辑和计算。XLSX 导入导出属于单独分发的文件转换能力,不在开源核心里,选型时要心里有数。
07踩坑实录
以下三个坑都是我这次实测真实撞上的,按撞上的顺序排:
坑一:分号。createUniver({...})的下一行紧跟(window as any).univerAPI = univerAPI时,TS 转译后两者会被拼接成createUniver({...})(window).univerAPI = ...——前者的返回值被当成函数调用,赋值静默失效,页面照样渲染。赋值语句前补一个分号即可。
坑二:locale。createUniver不传locales时画布也能出来,但 Ribbon 工具栏组件直接报错崩掉,页面没有 canvas。locale和locales两个选项必须同时给,key 必须用LocaleType.ZH_CN这个枚举值。
坑三:动态导入。CSS 和 locale 的包路径超过一行,拆成相邻字符串拼接是合法的:await import('@univerjs/preset-sheets-core' + '/lib/index.css')。但把路径存进变量再await import(cssPath)会失败,Vite 无法静态分析变量形式的裸包名导入,浏览器侧直接报 Failed to resolve module specifier。
顺手补一刀:静态 import 后面接 + 拼接字符串是语法错误,esbuild 直接拒绝编译,真实报错如下:
Pre-transform error:src/main2.ts:4:38: ERROR:Expected ";" but found "+"import '@univerjs/preset-sheets-core' + '/lib/index.css08进阶方向
▪︎ 给 Vite 配置别名,把长包路径收敛成 @univerjs/css 这类短名,代码更整洁
▪︎ 用 @univerjs/preset-sheets-filter、preset-sheets-sort、preset-sheets-advanced 等按需叠加筛选、排序、图表和透视表
▪︎ 把 Facade API 封装成 MCP 工具,让 Claude Code 这类 Agent 直接读写你的业务表格
▪︎ 结合公式引擎做无头计算服务:页面不渲染编辑器,只用它算带依赖关系的表单
09谁适合学
做过中后台就绕不开表格:报表、对账单、试验记录表、排期表,需求一深就从「展示表格」变成「编辑表格」。只要你的产品里有「用户要填、要算、要改」的表,Univer 就值得认真评估。
反过来,纯展示型的静态表格没必要上它,一个渲染组件足够。另外它的商用边界要清楚:核心引擎 Apache-2.0 开源,高级插件、Server 协同和 AI SDK 是单独授权的商业件,选型前先对一遍官方的功能对比表。
上手成本方面,TypeScript 类型完整,Facade API 命名和 Excel 心智一致(getRange、setValue、undo),前端工程师几乎零学习曲线;公式引擎的依赖图、命令系统的撤销栈这些深水区,等真有需求再钻不迟。
10参考资料
▪︎ 项目地址:github.com/dream-num/univer
▪︎ 官方文档:docs.univer.ai
▪︎ Quick Start 原文:github.com/dream-num/univer#quick-start
▪︎ npm 包:@univerjs/preset-sheets-core(本文实测版本 1.5.2)
▪︎ 数据核对于 2026 年 11 月 16 日:GitHub API + npm registry + 本机实测















































































