封面 · Univer 入门:它是什么,能做什么,怎么用

在 Web 系统中嵌入一个“像 Excel 那样好用”的电子表格,向来是一项复杂的工程。过去许多团队会选择曾经风靡一时的 Luckysheet,但随着 Luckysheet 归档停止维护,其原班团队 DreamNum 推出了全新的开源 Office SDK——Univer。

本文将从“是什么、能做什么、怎么用”三个维度带你快速了解 Univer,并理清它的内部设计与开源能力边界。


Univer 是什么

简单来说,Univer 是一套用于构建 Web 办公体验的开源 Office SDK。它的核心仓库基于 TypeScript 编写,遵循 Apache-2.0 开源许可证。

不同于传统仅提供 UI 视图的组件库,Univer 提供了包括内容模型、Canvas 渲染引擎、公式引擎、命令系统以及插件化依赖注入在内的完整底层基础设施。

不只是 UI:Univer 的底层基础设施

开发者可以通过引入 Univer 的 Web SDK,将高度可定制的电子表格(Sheets)或文档(Docs)编辑器直接嵌入到自有的 React、Vue 或原生 Web 应用中,无需通过 iframe 包装第三方在线文档服务。


它能做什么

在开源范畴内,Univer 提供了完整的 Sheets(表格) 和 Docs(文档) 基础编辑能力:

  1. Sheets 编辑与排版:支持多工作表管理、行/列增删与宽高调整、单元格合并、单元格内富文本、边框与背景色填充、冻结窗格、浮动图片以及历史记录(撤销/重做)。

  2. 数据处理与计算:内置公式引擎,支持常用的求和、统计、查找引用(如 VLOOKUP、INDEX/MATCH)、动态数组与 LAMBDA 表达式等,且支持将计算转移至 Web Worker 异步执行以减轻主线程压力;同时支持排序、筛选、数据验证(下拉框、复选框)以及条件格式。

  3. Docs 基础能力:支持段落样式、层级列表、行间距控制、分页与无分页模式切换。

  4. 快照持久化:能够将当前文档状态导出为可序列化的 JSON 快照(Snapshot),并能在需要时通过 JSON 快速恢复数据。

需要说明的是,开源支持并不等同于所有预设开箱即带,部分增强能力(如筛选、条件格式、数据验证等)需要按需引入对应的扩展插件或扩展预设。

具体场景:在后台系统嵌入可编辑的报价单

想象你正在搭建一个内部 CRM 或 ERP 系统。业务人员需要填报商品数量并查看实时折后总额。

借助 Univer,你可以在页面中直接嵌入一个表格,预填表头和单价。当用户修改数量单元格时,内置公式引擎会自动触发重新计算并刷新总额;保存时,业务系统直接调用 API 读取重新计算后的数值,并将整张表的 JSON 快照存入业务数据库。整个过程完全发生在前端,不依赖本地 Office 软件。

报价单场景:改数量到存快照


怎么用起来

1. 快速嵌入表格编辑器

Univer 提供了“预设模式(Presets)”,将核心插件和 UI 打包在一起,只需十几行代码即可在现代前端工程(如基于 Vite 的项目)中跑起来:

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

在页面中准备容器并初始化:

<div id="app" style="height: 100vh;"></div>
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'
import '@univerjs/preset-sheets-core/lib/index.css'

// 1. 初始化 Univer 实例
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
  },
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
      // 当前示例未启用 Worker(公式默认在主线程计算);如需启用,须单独创建 Worker 入口脚本并配置 workerURL
    }),
  ],
})

// 2. 创建一个空白工作簿
univerAPI.createWorkbook({})

上述代码完全基于开源包,无需商业授权即可在浏览器中展示一个具备基础编辑与公式计算能力的电子表格。如果业务还需要前文提到的筛选、条件格式或数据验证等功能,可以在此基础上继续叠加对应的功能插件或预设包。

2. 通过 Facade API 读写数据

初始化完成后,开发者可以通过返回的 univerAPI(Facade API)对工作簿和单元格进行程序化操作。新建工作簿后,需要等待编辑器进入 Steady 阶段,以确保公式控制器等核心服务初始化完成:

Facade API 读写的正确时序

// 等待公式控制器就绪后再执行编辑
await new Promise<void>((resolve) => {
  if (univerAPI.getCurrentLifecycleStage() >= univerAPI.Enum.LifecycleStages.Steady) {
    resolve()
    return
  }
  const listener = univerAPI.addEvent(univerAPI.Event.LifeCycleChanged, ({ stage }) => {
    if (stage === univerAPI.Enum.LifecycleStages.Steady) {
      listener.dispose()
      resolve()
    }
  })
})

const workbook = univerAPI.getActiveWorkbook()!
const sheet = workbook.getActiveSheet()

// 写入数据与公式
sheet.getRange('A1:D4').setValues([
  ['Item', 'Quantity', 'Unit price', 'Amount'],
  ['Seats', 2, 25, '=B2*C2'],
  ['Support', 1, 100, '=B3*C3'],
  ['Total', '', '', '=SUM(D2:D3)'],
])

// 外部代码修改数量
sheet.getRange('B2').setValue(4)

// 等待公式引擎计算完成,回读计算结果并保存快照
univerAPI.getFormula().onCalculationResultApplied().then(() => {
  console.log(sheet.getRange('D4').getValue()) // 输出: 200

  // 获取 JSON 快照用于持久化保存
  const snapshot = workbook.save()
  localStorage.setItem('quotation', JSON.stringify(snapshot))
}).catch(console.error)

如果需要重新打开已有内容,在页面重新加载时,直接将初始化代码中的 createWorkbook({}) 替换为 createWorkbook(JSON.parse(saved)) 传入保存的快照即可,无需先创建空白工作簿。

3. Node.js 中的 Headless 处理

由于 Univer 的内容模型与计算引擎与 DOM 视图层解耦,你还可以在没有界面的 Node.js 环境中引入相应插件,执行模板填充、离线公式计算及快照处理,非常适合自动化报表任务。


它是怎么组织的

相比早期将配置和逻辑混在一起的开源组件,Univer 在架构设计上有两项鲜明的特点:

1. 业务逻辑与 UI 插件严格分离

Univer 的模块大多成对出现。例如负责筛选规则与范围计算的是 @univerjs/sheets-filter,而负责弹出面板、菜单项和快捷键交互的则是 @univerjs/sheets-filter-ui。

这种分工带来了极高的扩展性:

  • 如果想给内部系统换一套完全不同的工具栏或定制浮层,只需替换或重写 UI 插件,核心数据逻辑不受影响;

  • 如果要在服务端 Node.js 运行公式计算,只需加载逻辑插件,完全不需要把庞大的 UI 代码打包进来。

2. 严密的命令与撤销系统

在电子表格中,很多操作是跨模块联动的。例如:在带有筛选的表格中插入一行,既需要变更底层单元格行数据,又需要同步调整筛选范围边界。

Univer 将这类操作拆解为三层概念:

  • Command(命令):编排整体业务逻辑,协调各个模块;

  • Mutation(变更):真正修改快照数据的可序列化操作,各模块同时提供正向和逆向 Mutation;

  • Operation(操作):只影响临时界面状态(如弹窗开关、滚动位置),不存入快照。

当插入行操作触发时,主 Command 会把基础行变更与筛选插件提供的变更组合在一起执行,并统一存入 IUndoRedoService。这样用户按 Ctrl+Z 时,就能一步同时恢复行列与筛选范围,避免状态不一致。

一次插入行,一步撤销:Command / Mutation / Operation


开源版不包含什么

在选型与技术评估时,需要明确 Univer 开源版与商业版的界限。

官方在功能对比文档中明确说明,开源版本仅包含前端编辑器,不包含服务端组件,且开源版的公式引擎性能低于商业版。具体而言,以下常见需求并不属于开源仓库的默认能力:

  • XLSX / DOCX 等 Office 文件导入与导出:开源包的 workbook.save() 保存的是 Univer 专属的 JSON 快照格式。若要直接读写本地 .xlsx 文件,需要配合单独授权的文件转换能力(Exchange,办公文件导入导出,属于 Server SDK 能力范畴)。

  • 多人实时协同与版本历史:多人在线协同涉及基于 OT(操作转换)算法的并发冲突解决、断网同步与服务端记录,这部分包含在独立的 Server SDK 中,开源版仅支持单人前端编辑。

  • 高级图表与数据透视表:数据透视表(Pivot Table)、切片器(Slicer)以及可交互的图表套件属于商业 Web SDK 插件。

  • Luckysheet 迁移成本:虽然两者出自同一团队,但由于架构、数据模型(IWorkbookData vs luckysheetfile)和 API 体系被彻底重构,Luckysheet 无法 1:1 无缝迁移到 Univer,原有的配置和业务代码需要重新适配。

开源版与商业能力的边界

对于绝大多数需要在 Web 页面中内嵌表格填报、参数配置和带公式计算的场景,开源版 Univer 凭借其清晰的架构、TypeScript 强类型支持与轻便的 Facade API,已经是一个足够扎实且现代化的选择。

声明:本站所有文章,如无特殊说明或标注,均为本站原创发布。任何个人或组织,在未征得本站同意时,禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益,可联系我们进行处理。