Univer 快速上手：10分钟把在线电子表格嵌进你的产品

Univer 快速上手：10分钟把在线电子表格嵌进你的产品

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer

Univer 是一个开源的全栈办公 SDK，覆盖电子表格、文档、幻灯片的编辑能力，同一套架构可以跑在浏览器和 Node.js 两端。读完这篇文章，你能在本地跑起来一个电子表格页面，并用几行 Facade API 完成批量写数据和公式计算。

它解决什么问题

典型场景：你的 SaaS 或 BI 系统要在页面里让用户编辑表格，但既不想 iframe 嵌一个别人的托管产品，也不想从零自研网格、选区、公式引擎。Univer 把表格、文档、演示拆成可嵌入的组件，模型层、渲染层、UI 层都交给你的应用接管；服务端还能用同一套 workbook 逻辑做无 UI 的 headless 处理，前端编辑和后端计算用一份代码打通。

从零到一，跑通第一次

1. 确认环境

这个 monorepo 要求 Node.js>=22.18、pnpm>=11，先确认版本：

node -v pnpm -v

不满足就先升级，后面所有步骤都依赖这两个版本。

2. 克隆仓库并安装依赖

git clone https://gitcode.com/GitHub_Trending/un/univer cd univer pnpm install

3. 启动示例应用

pnpm dev

这条命令会拉起examples/下的本地示例站点，浏览器打开控制台输出的地址，看到的就是一个完整的 Univer 电子表格界面。示例代码会把你最关心的univerAPI挂到window上，之后你在 DevTools 里可以直接调，不用自己再初始化。完整示例见 examples/src/preset-sheets-core/main.ts。

4. 嵌进自己的项目

如果不想跑示例，直接集成到自己的工程，用 Preset 模式最省事，两个包搞定：

pnpm add @univerjs/presets @univerjs/preset-sheets-core

入口文件这样写：

import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets' import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core' import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US' import '@univerjs/preset-sheets-core/lib/index.css' const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS), }, presets: [UniverSheetsCorePreset({ container: 'app' })], }) univerAPI.createWorkbook({})

页面里只需要一个有高度的挂载容器：

<div id="app" style="height: 100vh"></div>

createUniver帮你完成了插件注册和 Facade API 装配，univerAPI.createWorkbook({})之后表格里就有了一张空白工作表。

看到效果

跑起来后，#app容器内会出现带工具栏、行列表头和工作表标签页的电子表格界面：

判断它跑通了的标准很直接：点选任意单元格可以输入文字或数字，值会留在单元格里；在示例的浏览器控制台执行univerAPI.getActiveSheet()，能返回当前活动工作表的对象而不是报错。

把两个核心功能玩起来

批量填数据

Facade API 的FRange负责所有单元格读写，下面这段把表头样式和三行数据一次性写进去：

const sheet = univerAPI.getActiveSheet() sheet.getRange('A1:C1').setValues([[ { v: '姓名', s: { bg: { rgb: '#FFF3BF' } } }, { v: '年龄' }, { v: '邮箱' }, ]]) sheet.getRange('A2:C4').setValues([ ['张三', 25, 'zhangsan@example.com'], ['李四', 30, 'lisi@example.com'], ['王五', 35, 'wangwu@example.com'], ])

保存后刷新页面，表头会带底色，A2:C4 立刻出现三行数据。CSV 导入、模板初始化这类场景，用setValues一次写矩形区域即可，不需要逐格循环。写样式、设公式等方法都定义在 FRange Facade 源码 里，查文档不如直接看这个文件的 JSDoc。

让公式引擎算账

Univer 自带独立的公式引擎，写入公式后同步出结果：

sheet.getRange('A5').setFormulas([['=SUM(A2:A4)']])

A5 立刻显示 90，不需要任何手动"计算"动作。公式会参与工作簿的数据模型，撤销、重做、跨表引用都按正常表格行为处理。想理解它内部如何解析和求值，可以读 公式引擎架构笔记，再配合 packages/engine-formula/ 的源码看实现。

卡住时的常见问题

页面加载后 #app 一片空白？容器必须有显式高度，<div id="app" style="height: 100vh">这行样式不能省，高度为 0 时渲染引擎不会铺画布。

同时装了多个 @univerjs 包，版本不一致会怎样？会出各种诡异报错。README 明确要求所有@univerjs/*包保持同一版本，升级时整体一起升。

pnpm dev 起不来，或浏览器里报错？先对照环境要求：Node>=22.18、pnpm>=11；浏览器兼容性目标是 Chrome 88+、Safari 14.1+，更老的浏览器需要补Intl.Segmenter的 polyfill。

接下来去哪

• examples/src/preset-sheets-core/main.ts：带中文语言包和筛选、排序、条件格式等十余个插件的完整 Preset 集成示例
• presets/：所有可直接安装的 Preset 包清单
• packages/sheets/README.md：表格核心包的说明文档
• docs/API_STABILITY.md：API 稳定性策略，区分稳定、实验和内部接口
• docs/tldr/：公式引擎、Web Worker、选区等主题的架构速记

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer