
用 Univer Office SDK 构建你的 AI 办公产品
从开源的 Sheets 和 Docs 开始,再连接你自己的应用或 Agent。
🚀 快速开始 · 💼 Workspace · 📚 开发文档 · ⚖️ 功能对比 · 🌐 官网 · 🎮 示例 · 🔧 API 参考 · 📝 博客
English · Français · Deutsch · Español · 简体中文 · 繁體中文 · 日本語 · 한국어
目录
- [💡 Univer 是什么?](#what-is-univer)
- [开源能力](#open-source-capabilities)
- [🚀 基于开源基础构建](#what-you-can-build)
- [快速开始:开源电子表格编辑器](#quick-start)
- [将应用连接到可编辑内容](#connect-your-application-to-editable-content)
- [🏗️ 探索开源架构](#open-source-architecture)
- [为自定义功能划分清晰边界](#give-custom-features-clear-boundaries)
- [组合跨功能编辑与撤销/重做](#compose-cross-feature-edits-and-undoredo)
- [通过 Facade API 和事件连接应用与 Agent](#connect-applications-and-agents-through-facade-apis-and-events)
- [🧩 使用 Univer Office SDK 扩展应用](#open-source-and-commercial-extensions)
- [范围与授权](#scope-and-licensing)
- [🌐 应用模式与生态](#application-patterns-and-ecosystem)
- [Univer Workspace:Office SDK 参考应用](#univer-workspace-an-office-sdk-reference-application)
- [CLI、Agent 集成与开发技能](#cli-agent-integrations-and-developer-skills)
- [📚 文档与贡献](#documentation-and-contributing)
- [运行环境兼容性](#runtime-compatibility)
- [💬 社区](#community)
- [🔒 安全](#security)
- [❤️ 赞助](#sponsors)
- [📄 许可证](#license)
## 💡 Univer 是什么?

**Univer** 是一套 Office SDK,用于在你自己的产品中构建办公应用。它基于你的数据和权限,为用户和现有 Agent 提供办公编辑、计算、协作及文件处理能力。产品系列覆盖电子表格、文档、演示文稿、关联表格、画布和 PDF。

Univer Office SDK 由三部分组成:
- **Web SDK** 是基础,包含内容模型、编辑、渲染、公式计算和 Facade API(面向应用的 API)。通过组合插件,可以构建嵌入式编辑器或自己的办公应用,也可以在没有交互式编辑器的情况下,复用内容模型、命令和计算能力进行 Headless 处理。
- **Server SDK** 提供实时协作、编辑历史和办公文件导入导出的后端服务。
- **AI SDK** 通过内容工具、执行和审阅集成,将办公能力连接到现有 Agent 和工作流程。
**本仓库以 Apache-2.0 许可证提供 Web SDK 的核心架构和引擎实现**,包括内容模型与快照格式、插件与依赖管理、命令系统、公式与渲染引擎、Facade API、UI 基础设施,以及 Sheets 和 Docs 编辑能力。商业 Web SDK 插件、Server SDK 和商业 AI SDK 扩展单独分发和授权。
Agent 可以使用同样的开源 API,模型和工具编排由你的应用提供。[报价单示例](#connect-your-application-to-editable-content)展示了不依赖 AI SDK 的编辑、计算和保存流程。
### 开源能力
| 领域 |
部分能力 |
| Sheets · 编辑与布局 |
单元格样式、合并单元格、单元格内富文本、冻结窗格、浮动图片,以及撤销/重做。 |
| Sheets · 数据与计算 |
公式、定义名称、筛选、排序、数据验证、条件格式、超链接、评论,以及查找替换。 |
| Docs |
富文本编辑、段落格式、列表、超链接、评论和绘图集成。 |
功能通过插件和预设组合;[快速开始](#quick-start)仅使用 **Sheets Core 预设**。图片需要相应的绘图插件。详细的开源和商业能力范围请参阅[功能对比](https://univer.ai/compare/)。
以下演示展示更完整的 **Univer Office SDK**,包括商业能力,其范围超出默认开源配置;具体请参阅[开源与商业扩展](#open-source-and-commercial-extensions)。

## 🚀 基于开源基础构建

| 你的目标 |
使用开源基础 |
从这里开始 |
| 嵌入 Sheets 或 Docs |
为应用或 Agent 产品添加可编辑的办公界面,并通过 Facade API 连接数据。 |
快速开始 |
| 在没有编辑器的情况下处理内容 |
在 Node.js 中复用内容插件、模型、命令和计算能力,用于编辑、快照和自动化任务。 |
Headless 指南 |
| 开发自定义功能或编辑器 |
复用引擎、UI 组件、插件边界、依赖注入及命令/撤销系统。参考现有功能扩展 Sheets 和 Docs,或开发自己的编辑器。 |
开源架构 |
**协调跨功能的编辑与撤销/重做。** 在筛选范围内插入一行,会同时改变基础内容和筛选范围,撤销时也需要同时恢复两者。各功能提供自己的变更和撤销数据,由命令组合执行并记录历史。架构介绍会说明如何扩展这些编辑流程。
### 快速开始:开源电子表格编辑器
在使用 Vite 等构建工具的浏览器应用中:
```bash
pnpm add @univerjs/presets @univerjs/preset-sheets-core
```
初始化 Univer 前,先创建容器:
```html
```
```ts
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'
const { univerAPI } = createUniver({
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
},
presets: [
UniverSheetsCorePreset({
container: 'app',
}),
],
})
univerAPI.createWorkbook({})
```
现在,页面中已经有了电子表格编辑器。使用返回的 `univerAPI` 操作其内容。本示例使用开源包,无需商业 Univer 许可证或 Server SDK。
对于组件框架,请保留 `createUniver` 返回的 `univer` 实例,并在组件卸载时调用 `univer.dispose()`。参阅[生命周期指南](https://docs.univer.ai/guides/sheets/getting-started/lifecycle)。
预设会组合插件并注册其 Facade API。如需手动控制,请参阅下方的[插件模式示例](#manual-plugin-composition)。[安装指南](https://docs.univer.ai/guides/sheets/getting-started/installation)涵盖两种模式、对等依赖和框架集成。
需要配套使用的 `@univerjs/*` 包应保持同一版本。商业包必须匹配相应的发布系列;图标等独立发布的包遵循各自声明的兼容性。参阅 [API 稳定性策略](../../docs/API_STABILITY.md)。
### 将应用连接到可编辑内容
Facade API 是面向应用的工作簿、工作表和范围接口。继续快速开始的示例,填入报价单,从应用代码更新数量,并读取重新计算后的总额:
```ts
// Wait for formula controllers before editing a newly created workbook.
await new Promise((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)'],
])
// An application control or agent can make the same edit.
sheet.getRange('B2').setValue(4)
univerAPI.getFormula().onCalculationResultApplied().then(() => {
console.log(sheet.getRange('D4').getValue()) // 200
localStorage.setItem('quotation', JSON.stringify(workbook.save()))
}).catch(console.error)
```
编辑器与应用操作同一份工作簿,公式变更会自动重新计算。`workbook.save()` 返回包含工作簿及已注册插件数据的 JSON 快照。持久化由你的应用负责,本示例使用浏览器存储。之后再次加载页面时,在初始化后恢复快照,**而不是创建空白工作簿**:
```ts
const saved = localStorage.getItem('quotation')
if (saved) {
univerAPI.createWorkbook(JSON.parse(saved))
}
```
此流程仅使用开源包。快照持久化与 XLSX 导入导出是不同的能力,后者需要单独分发的文件转换能力。应用集成应使用公开的 Facade API;下方源码链接说明内部实现和扩展点。依赖扩展点前,请参阅 [API 稳定性策略](../../docs/API_STABILITY.md)。
进阶:手动组合插件(插件模式)
当你需要精确控制插件选择、依赖或加载方式时,可以使用插件模式。上方的预设会代你完成这些组合工作。
这套替代初始化方式使用相同的 `app` 容器和 Sheets Core 预设的浏览器插件栈,不使用 Worker。请用它**替代**预设初始化,然后使用返回的 `univerAPI` 运行同一份报价单示例。
```bash
pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui \
@univerjs/engine-formula @univerjs/engine-render @univerjs/network \
@univerjs/sheets @univerjs/sheets-ui @univerjs/sheets-formula \
@univerjs/sheets-formula-ui @univerjs/sheets-numfmt \
@univerjs/sheets-numfmt-ui @univerjs/ui
```
```ts
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
import DesignEnUS from '@univerjs/design/locale/en-US'
import { UniverDocsPlugin } from '@univerjs/docs'
import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
import FormulaEnUS from '@univerjs/engine-formula/locale/en-US'
import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
import { UniverNetworkPlugin } from '@univerjs/network'
import { UniverSheetsPlugin } from '@univerjs/sheets'
import SheetsEnUS from '@univerjs/sheets/locale/en-US'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import SheetsFormulaEnUS from '@univerjs/sheets-formula/locale/en-US'
import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US'
import { UniverUIPlugin } from '@univerjs/ui'
import UIEnUS from '@univerjs/ui/locale/en-US'
import '@univerjs/design/lib/index.css'
import '@univerjs/ui/lib/index.css'
import '@univerjs/docs-ui/lib/index.css'
import '@univerjs/sheets-ui/lib/index.css'
import '@univerjs/sheets-formula-ui/lib/index.css'
import '@univerjs/sheets-numfmt-ui/lib/index.css'
import '@univerjs/network/facade'
import '@univerjs/docs/facade'
import '@univerjs/docs-ui/facade'
import '@univerjs/engine-formula/facade'
import '@univerjs/sheets/facade'
import '@univerjs/ui/facade'
import '@univerjs/sheets-ui/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'
import '@univerjs/sheets-formula-ui/facade'
const univer = new Univer({
locale: LocaleType.EN_US,
locales: {
[LocaleType.EN_US]: mergeLocales(
DesignEnUS,
DocsUIEnUS,
FormulaEnUS,
SheetsEnUS,
SheetsFormulaEnUS,
SheetsFormulaUIEnUS,
SheetsNumfmtUIEnUS,
SheetsUIEnUS,
UIEnUS,
),
},
})
univer.registerPlugin(UniverNetworkPlugin)
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverUIPlugin, { container: 'app' })
univer.registerPlugin(UniverDocsUIPlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverSheetsPlugin, {
onlyRegisterFormulaRelatedMutations: false,
})
univer.registerPlugin(UniverSheetsUIPlugin, {
protectedRangeShadow: true,
})
univer.registerPlugin(UniverSheetsNumfmtPlugin)
univer.registerPlugin(UniverSheetsNumfmtUIPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsFormulaUIPlugin)
const univerAPI = FUniver.newAPI(univer)
univerAPI.createWorkbook({})
```
Docs 插件支持电子表格中的富文本编辑。添加功能时,请同时引入对应的 Facade 扩展、语言包和 UI 样式。容器卸载时应销毁 `univer`。

## 🏗️ 探索开源架构

### 为自定义功能划分清晰边界
Univer 使用不同的插件组织内容逻辑与 UI 交互。功能插件管理规则和内容变更,UI 插件提供界面及用户交互。例如,`sheets-filter` 管理筛选范围与规则,`sheets-filter-ui` 提供面板、菜单和快捷键。
```mermaid
%%{init: {'htmlLabels': false, 'theme': 'base', 'themeVariables': {'fontFamily': 'Arial, PingFang SC, Microsoft YaHei, sans-serif', 'fontSize': '17px', 'lineColor': '#64748b'}, 'flowchart': {'htmlLabels': false, 'curve': 'linear', 'nodeSpacing': 28, 'rankSpacing': 45, 'padding': 16, 'wrappingWidth': 270}}}%%
%% A layered overview, not a complete dependency graph.
%% Group arrows indicate reuse of the layer below; internal arrows show selected dependencies.
flowchart TD
subgraph FEATURES["Feature Plugins"]
direction LR
FUI["Filter
UI Plugin"]
VUI["Data Validation
UI Plugin"]
FILTER["Filter Plugin"]
VALIDATION["Data Validation Plugin"]
FUI --> FILTER
VUI --> VALIDATION
end
subgraph PRODUCTS["Product Plugins"]
direction LR
SUI["Sheets UI Plugin"]
SHEETS["Sheets Plugin"]
SUI --> SHEETS
end
subgraph FOUNDATION["Core Framework & Plugins"]
direction LR
UI["UI Plugin"]
FORMULA["Formula Engine Plugin"]
RENDER["Render Engine Plugin"]
CORE["Core"]
UI --> RENDER
RENDER --> CORE
FORMULA --> CORE
end
FEATURES --> PRODUCTS
PRODUCTS --> FOUNDATION
classDef logic fill:#eff6ff,color:#17365f,stroke:#93b4df,stroke-width:1.5px
classDef ui fill:#f0fdf4,color:#17543a,stroke:#91c8a7,stroke-width:1.5px
classDef shared fill:#f6f7f9,color:#334155,stroke:#bac3ce,stroke-width:1.5px
classDef feature fill:#172d50,color:#ffffff,stroke:#172d50
class FUI,VUI ui
class FILTER,VALIDATION logic
class SUI,SHEETS logic
class UI,FORMULA,RENDER,CORE shared
style FEATURES fill:#f7fcf9,stroke:#b5d8c1,color:#17543a
style PRODUCTS fill:#f5f9ff,stroke:#b6cbea,color:#17365f
style FOUNDATION fill:#fafbfc,stroke:#cbd2dc,color:#334155
```
**图 1:三层插件结构。** 功能插件建立在产品插件之上,产品插件复用核心框架与插件。分组箭头表示对下一层的依赖;Core 提供内容模型、命令、依赖注入和生命周期管理。图中省略了部分插件与依赖。
新功能将规则保留在自己的插件中,通过公开服务、命令和明确的扩展点协作。UI 插件建立在共享的 UI 服务与组件之上。
依赖关系在两个层面明确声明:
- **插件之间:** `DependentOn` 声明运行时插件依赖。插件服务对其排序,生命周期阶段将依赖注册、内容初始化和 UI 初始化分开。
- **插件内部:** 依赖注入通过声明的依赖连接控制器与服务。受支持的覆盖机制允许应用替换实现、适配平台服务或提供测试替身。实例级注入器将不同 Univer 实例的应用状态隔离。
可释放的注册机制也让命令、监听器、组件和图标在所属对象销毁时得到清理。
[筛选插件](../../packages/sheets-filter/src/plugin.ts)及其 [UI 插件](../../packages/sheets-filter-ui/src/plugin.ts)在实际代码中展示了这些边界。
功能内部:Model、Controller、Service 和 UI 基础设施
在筛选功能中,`sheets-filter` 负责内容逻辑,`sheets-filter-ui` 负责 UI 交互,每个模块各司其职。
```mermaid
%%{init: {'htmlLabels': false, 'theme': 'base', 'themeVariables': {'fontFamily': 'Arial, PingFang SC, Microsoft YaHei, sans-serif', 'fontSize': '17px', 'lineColor': '#64748b'}, 'flowchart': {'htmlLabels': false, 'curve': 'linear', 'nodeSpacing': 28, 'rankSpacing': 45, 'padding': 16, 'wrappingWidth': 270}}}%%
%% Every arrow means contains. This is code organization, not execution order.
flowchart LR
FEATURE["Filter Feature"]
LOGIC["Filter Plugin"]
UI["Filter UI Plugin"]
MODEL["Model"]
SERVICE["Service"]
CONTROLLER["Controller"]
COMMAND["Command / Mutation"]
FACADE["Facade API"]
VIEW["View"]
UICTRL["UI Controller"]
UISERVICE["UI Service"]
FEATURE --> LOGIC
FEATURE --> UI
LOGIC --> MODEL
LOGIC --> SERVICE
LOGIC --> CONTROLLER
LOGIC --> COMMAND
LOGIC --> FACADE
UI --> VIEW
UI --> UICTRL
UI --> UISERVICE
classDef logic fill:#eff6ff,color:#17365f,stroke:#93b4df,stroke-width:1.5px
classDef ui fill:#f0fdf4,color:#17543a,stroke:#91c8a7,stroke-width:1.5px
classDef shared fill:#f6f7f9,color:#334155,stroke:#bac3ce,stroke-width:1.5px
classDef feature fill:#172d50,color:#ffffff,stroke:#172d50
class FEATURE feature
class LOGIC,MODEL,SERVICE,CONTROLLER,COMMAND,FACADE logic
class UI,VIEW,UICTRL,UISERVICE ui
```
**图 2:代码组织。箭头表示“包含”。** 两种插件都可以包含 Controller 和 Service:逻辑 Controller 协调内容变更与相关功能;UI Controller 连接菜单、快捷键和交互,UI Service 管理面板状态。这些职责为新功能的实现与测试提供一致的结构。
UI 基础设施采用相同的职责划分。**`@univerjs/design`** 提供共享组件和样式,**`@univerjs/ui`** 提供菜单、快捷键、面板和组件注册等工作台服务,**`@univerjs/icons`** 提供图标。功能通过这些扩展点注册组件和图标、添加菜单并接入渲染。团队可以在复用应用 UI 基础设施的同时添加面板或工具栏功能。参阅 [UI 概览](https://docs.univer.ai/guides/sheets/ui/overview)和筛选插件的[组件与图标注册](../../packages/sheets-filter-ui/src/controllers/components.controller.ts)。
### 组合跨功能编辑与撤销/重做
例如,在筛选范围内插入行时,筛选插件提供相应的范围变更及撤销数据。插行命令组合基础编辑和参与功能的变更,执行它们,并统一记录撤销/重做信息。插行功能可以使用共享的扩展机制,筛选插件则负责自身的范围更新规则。
命令系统区分三种操作:
- **Command** 编排业务操作及其所需的变更。
- **Mutation** 以可序列化参数修改保存在快照中的内容。
- **Operation** 修改临时状态,例如打开的面板或滚动位置。
**统一的撤销/重做结构。** 对于可撤销的编辑,功能实现提供正向 Mutation 和对应的逆向 Mutation,Command 通过 `IUndoRedoService` 记录它们。当一个操作影响多个功能时,Command 可以将它们的变更与撤销数据合并为一条记录,使用户能够完整地撤销和重做该操作。参阅[扩展命令](https://docs.univer.ai/blog/custom-command)。
功能之间仍然需要协作。**拦截器与引用范围处理器为这种协作提供明确的位置。** 在受支持的扩展点,插件提供检查或相关 Mutation;在 API 定义的范围内,拦截器优先级控制执行顺序。
示例:命令、回调、功能协作与撤销/重做
```mermaid
%%{init: {'htmlLabels': false, 'theme': 'base', 'themeVariables': {'fontFamily': 'Arial, PingFang SC, Microsoft YaHei, sans-serif', 'fontSize': '17px', 'lineColor': '#64748b'}, 'flowchart': {'htmlLabels': false, 'curve': 'linear', 'nodeSpacing': 28, 'rankSpacing': 45, 'padding': 16, 'wrappingWidth': 270}}}%%
%% Simplified insert-row example. A command composes mutations and records undo after success.
%% Events may also fire for nested command executions; not every callback is drawn.
flowchart TD
BEFORE["Before execution
Inspect or cancel"]
CMD["Insert-row Command"]
BASE["Row mutations"]
EXT["Feature extension points
Filter range changes"]
MODEL["Execute combined mutations"]
UNDO["Record undo and redo"]
AFTER["After execution
Notify listeners"]
BEFORE --> CMD
CMD --> BASE
CMD --> EXT
BASE --> MODEL
EXT --> MODEL
MODEL --> UNDO
UNDO --> AFTER
classDef entry fill:#f6f7f9,color:#334155,stroke:#bac3ce,stroke-width:1.5px
classDef core fill:#eff6ff,color:#17365f,stroke:#93b4df,stroke-width:1.5px
classDef extension fill:#f0fdf4,color:#17543a,stroke:#91c8a7,stroke-width:1.5px
class BEFORE,AFTER entry
class CMD,BASE,MODEL,UNDO core
class EXT extension
```
此图简化了插行流程。嵌套命令有各自的执行回调;图中未展示全部事件,也未展示独立的 Operation 路径。参阅[行命令](../../packages/sheets/src/commands/commands/insert-row-col.command.ts)、[筛选控制器](../../packages/sheets-filter/src/controllers/sheets-filter.controller.ts)和[拦截器服务](../../packages/sheets/src/services/sheet-interceptor/sheet-interceptor.service.ts)。
这些边界支持实用的测试策略:独立测试模型和服务,通过依赖注入替换外部依赖,并为组合操作与撤销/重做补充回归用例。[筛选控制器测试](../../packages/sheets-filter/src/controllers/__tests__/sheets-filter.controller.spec.ts)覆盖行列变更及其对筛选的影响。
### 通过 Facade API 和事件连接应用与 Agent
本仓库包含编辑器背后的内容模型、公式引擎,以及 Canvas 渲染与布局引擎。它们是共享的基础模块;例如,电子表格的富文本会复用文档的布局和渲染。自定义功能可以基于这些引擎构建,无需另行实现内容技术栈。参阅[公式引擎架构](https://docs.univer.ai/blog/formula)和[渲染引擎架构](https://docs.univer.ai/blog/rendering)。
浏览器编辑器、Node.js 中的 Headless 任务,以及合理组合的 Worker,都可以复用相应的内容插件、模型、命令和计算能力。参阅 [Headless Univer](https://docs.univer.ai/guides/sheets/getting-started/node)和[同构架构](../../docs/ISOMORPHIC.md)。
`ICommandService` 提供执行回调,使插件能够在命令执行前后进行观察。Facade API 将底层能力封装为 `FWorkbook`、`FWorksheet` 和 `FRange` 等面向应用的对象。
各插件提供自己的 Facade 扩展、**通过 `univerAPI.Event` 暴露的类型化事件**,以及**通过 `univerAPI.Enum` 暴露的枚举**。应用代码可以从统一入口查找事件名与常量,无需导入私有服务或重复编写字符串。例如,`BeforeCommandExecute` 可以检查并取消执行,`CommandExecuted` 向监听器报告执行情况。监听器返回可释放对象,取消仅在事件支持时生效。
Facade 扩展随各自的功能包提供,因此内容 API 不必引入无关的 UI API。参阅 [Facade 设计](https://docs.univer.ai/blog/facade)、[命令回调与事件桥接](../../packages/core/src/facade/f-univer.ts)和 [Enum 入口](../../packages/core/src/facade/f-enum.ts)。
本仓库提供可用的功能实现及扩展模式。完整示例请阅读[筛选功能实现解析](https://docs.univer.ai/blog/anatomy);依赖扩展点前,请参阅 [API 稳定性策略](../../docs/API_STABILITY.md)。

## 🧩 使用 Univer Office SDK 扩展应用

需要更多可直接集成的能力时,可以组合相应的 **Univer Office SDK** 模块,包括更多内容类型、高级编辑插件、协作、文件转换和 Agent 工具。它们扩展上文介绍的同一套内容模型、插件架构、命令系统和 Facade 设计,因此可以在现有集成之上继续构建。
| 组成 |
如何扩展开源基础 |
| 开源 Web SDK 核心 · 本仓库 |
开源的模型、引擎、插件、UI 基础设施,以及 Sheets 和 Docs 能力,并提供相应的 Headless 内容操作。可依据 Apache-2.0 许可证用于商业应用。 |
| 商业 Web SDK 插件 |
遵循核心的 Plugin、依赖注入、Command/Mutation 和 Facade 扩展模式,为相应内容类型添加图表、形状、透视表、SmartArt 等功能。 |
| Server SDK |
基于相同的内容模型和 Mutation 约定,增加实时协作、版本历史和办公文件转换,并与应用的身份、权限和存储系统集成。 |
| AI SDK 扩展 |
复用 Web SDK 的 Headless 与 Facade 能力,提供可组合的 Node.js API 和 CLI 基础模块,让 Agent 检查、编辑和验证内容,并集成协作与 Worktree 审阅。 |
### 范围与授权
- **本仓库:** 采用 Apache-2.0 许可证的包,可依据该许可证用于商业应用,包括开源的 Headless 内容能力。
- **商业扩展:** 商业 Web SDK 插件、Server SDK 及超出开源基础的 AI SDK 能力单独分发和授权。**Freemium** 评估包含水印和功能限制。
- **参考应用:** Univer Workspace 等开源应用具有自己的源码许可证,其 SDK 依赖仍遵循各自的许可证。
详细覆盖范围请查看[功能对比](https://univer.ai/compare/),其中提供 **Open source only(仅开源)** 筛选;商业选项请查看[方案与授权](https://univer.ai/pricing/)。
共享内容模型如何连接编辑、协作与文件
这些能力操作可序列化的 **Unit 快照**,包括 Sheets 的 `IWorkbookData`、Docs 的 `IDocumentData`、Slides 的 `ISlideData`,以及画布的 `IBoardData`(API 中称为 **Boards**)。这些类型来自 core 和相应产品包;当前 Slides 和 Boards 能力属于单独分发的商业产品。共享的 Unit 约定让浏览器编辑器、后端服务和 Agent 能够处理同一份内容。
Command 编排编辑,**Mutation 描述内容变更**。协作将 Mutation 打包为 **changeset(变更集)**,通过**操作转换(OT)**处理并发变更,并管理已确认的版本和快照。历史功能可以从快照及后续变更集重建某个版本。参阅[协作设计](https://docs.univer.ai/blog/ot)和 [Collaboration SDK 概览](https://docs.univer.ai/server/collaboration/overview)。
**Exchange** 在办公文件结构与 Univer 内容快照之间进行转换。对于 **XLSX、DOCX 和 PPTX** 等 OOXML 格式,它将文件解析为对应的 Sheet、Doc 或 Slide 数据,并在导出时生成文件表示。转换后的内容可以进入同样的编辑、计算、协作和 Agent 工作流程。参阅[办公文件导入导出](https://docs.univer.ai/server/import-export/node)。
AI SDK 如何向 Agent 提供相同的内容能力
AI SDK 建立在 Web SDK 的 **Headless 内容模型、命令、计算和 Facade API** 之上,提供结构化的 TypeScript API 及可选的 Commander 预设,供应用组合自己的 Office CLI 或 Agent 工具。
- **理解、发现和编辑。** 检查会返回结构化内容。API Reference 帮助 Agent 查找随 SDK 发布的 Facade 符号与签名。Facade 执行区分读写模式、捕获 Mutation,并提供明确的同步和提交结果。参阅[内容操作](https://docs.univer.ai/ai/content-operations)。
- **检查渲染结果。** 浏览器 Render Runtime 复用 Web SDK 渲染来生成截图。幻灯片布局检查会返回文字超出页面、重叠等问题的结构化结果,为 Agent 的下一轮编辑提供依据。参阅[视觉检查](https://docs.univer.ai/ai/visual-inspection)。
- **编辑草稿供人工审阅。** 配合相应的协作和 Web 能力,Agent 可以在隔离的 Worktree 草稿中进行多轮编辑与验证,再交给用户审阅、合并或重新打开。流程沿用相同的快照、Mutation 和版本约定。参阅 [Worktree](https://docs.univer.ai/ai/worktree)。
对于重复调用,可选的 [Worker 池和守护进程](https://docs.univer.ai/ai/runtime-architecture)可以复用已加载的内容实例,减少重复初始化。根 CLI、目标、授权和输出由应用负责。请通过 [AI SDK 包目录](https://docs.univer.ai/ai/packages)选择所需能力。

## 🌐 应用模式与生态

### Univer Workspace:Office SDK 参考应用
需要完整应用参考时,可以从 [Univer Workspace](https://github.com/dream-num/univer-workspace) 开始。它展示了如何将 Univer Office SDK 编辑器、协作、文件能力、现有 Agent 和人工审阅组合成可自行托管的工作空间。构建自己的办公应用或 Agent 工作空间时,可以参考其集成模式。
Workspace 是开源应用,其 SDK 依赖遵循各自的许可证。关联应用和审阅流程请参阅 [Workspace 概览](https://univer.ai/workspace/)。

[观看 SDK 集成演示](https://www.youtube.com/watch?v=1p-SMEiK6Kg)
### CLI、Agent 集成与开发技能
同样的 SDK 能力也可以组合进你已经使用的 Agent 和工具中:
各仓库均提供配置说明和 SDK 依赖说明。可浏览[生态](https://univer.ai/ecosystem/)了解 Agent 入口,或参考[文档](https://docs.univer.ai/)构建自己的集成。

## 📚 文档与贡献
感谢所有参与构建和改进 Univer 的[贡献者](https://github.com/dream-num/univer/graphs/contributors)。欢迎贡献引擎、插件、测试、文档和示例。
🧩 Web SDK · 🖥️ Server SDK · 🤖 AI SDK · 🔧 API 参考 · 🎮 在线示例
 Edge |
 Firefox |
 Chrome |
 Safari |
 Electron |
>=88 |
>=90 |
>=88 |
>=14.1 |
>=12 |
Univer 以 Chrome 88 为编译目标,旨在支持上表所列版本。
### 运行环境兼容性
- **Polyfill**:Univer 依赖 `Intl.Segmenter`。如果目标浏览器或运行时未提供该 API,请添加 `@formatjs/intl-segmenter` 等 Polyfill。
- **构建工具**:推荐 Vite、esbuild 或 Webpack 5。如果构建工具不支持 `package.json` 中的 `exports` 字段(常见于 Webpack 4),可能需要额外的路径映射。
- **React**:Univer 的视图层基于 React 18 构建,支持 React 18 和 19,并为 React 16.9+ 和 17 提供最低限度的兼容支持。
- **Node.js 环境**:Headless Univer 支持 Node.js `>=18.17.0`,开发本仓库需要 Node.js `>=22.18`。
在本仓库中开发
### 仓库结构
```text
.
├── packages/ Core packages, engines, document types, UI plugins, and feature plugins
├── examples/ All-in-one Vite workbench used for local browser development
├── common/ Shared internal tooling, storybook, and utilities
├── tests/ Additional integration test projects
└── docs/ Architecture notes, images, and repository-local documentation
```
各包的 README 位于 [`packages/`](../../packages) 下对应包的目录中。
### 本地开发
环境要求:
- Node.js `>=22.18`
- pnpm:使用 `package.json` 中 `packageManager` 声明的版本。
```bash
git clone https://github.com/dream-num/univer.git
cd univer
pnpm install
pnpm dev
```
常用命令:
| 命令 |
用途 |
pnpm dev |
启动 Sheets 和 Docs 开发工作台。 |
pnpm build |
构建工作区包,不包括内部 common 包。 |
pnpm test |
通过 Turbo 运行单元测试。 |
pnpm typecheck |
通过 Turbo 运行 TypeScript 检查。 |
pnpm lint |
运行 ESLint。 |
pnpm storybook:dev |
启动 Storybook 进行 UI 组件开发。 |
提交 Pull Request 前,请阅读 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
架构与贡献参考
- [仓库中的包](../../packages)、[预设](../../presets)和[示例](../../examples)。
- [构建同构 Univer](../../docs/ISOMORPHIC.md)。
- [Facade API 贡献指南](../../docs/CONTRIBUTING-FACADE.md)。
- [API 稳定性策略](../../docs/API_STABILITY.md)。
- [命名规范](../../docs/NAMING_CONVENTION.md)和[内存泄漏修复](../../docs/FIX_MEMORY_LEAK.md)。
- [架构 TLDR](../../docs/tldr)和 [OLE 附件说明](../../packages/drawing/docs/ole-attachments.md)。

## 💬 社区
在 [GitHub Discussions](https://github.com/dream-num/univer/discussions) 提问,加入 [Discord](https://discord.gg/z3NKNT6D2f),并关注 [X](https://twitter.com/univerhq) 或 [YouTube](https://www.youtube.com/@dreamNum)。请阅读[行为准则](../../CODE_OF_CONDUCT.md)。
微信扫码加入 Univer 交流群:


## 🔒 安全
如果你认为发现了安全问题,请遵循 [安全政策](../../SECURITY.md)。

## ❤️ 赞助
Univer 由社区和赞助者共同支持。你可以通过 [Open Collective](https://opencollective.com/univer) 支持这个项目。

## 📄 许可证
Copyright (c) 2021-present DreamNum Co., Ltd.
本仓库的开源包采用 [Apache-2.0](../../LICENSE) 许可证。商业 SDK 模块单独分发和授权。
