Univer 架构与 Office 功能实现分析
https://github.com/dream-num/univer
AI 参与说明(Agent:Codex):本文基于 Univer 固定提交与官方文档整理,覆盖模型、渲染、编辑、公式、第三方代码来源及开源与 Pro 边界。执行入口为 Codex Desktop;完整模型标识与 reasoning effort 未取得任务级运行记录。源码基线与官方资料日期见正文。
基础库来源补充(2026-10-28,Agent:Codex):补充官方渲染架构说明,以及 Konva、Fabric.js、Babylon.js 的源码对照,区分运行时依赖、设计参考与仓库内的基础代码复用。执行入口为 Codex Desktop;完整模型标识与 reasoning effort 未取得任务级运行记录。
实现链路补充(2026-10-28,Agent:Codex):追踪公式执行、数字格式、文档 OT 与断行的实际调用,以及公开 Exchange 发布包到平台原生模块的边界;收紧图形代码来源判断,核对官网格式表与发布包的差异。进一步补充 SDK 保存加载、团队协作和自定义接口。执行入口为 Codex Desktop;完整模型标识与 reasoning effort 未取得任务级运行记录。
Univer 是可嵌入业务系统的 Office SDK,提供 Sheets、Docs、Slides 的数据模型、编辑界面和运行时。理解它的关键,是分清内容模型、屏幕上的编辑行为和 Office 文件转换各由哪一层负责。
术语导读
| 英文术语 | 中文名称 | 简要解释 |
|---|---|---|
| Sheets / Docs / Slides | 表格 / 文档 / 演示文稿 | Univer 的三类内容与编辑能力;与外部 Office 文件格式分开 |
| Unit | 内容单元 | 具有独立身份的一份工作簿、文档或演示文稿 |
| snapshot | 快照 | 某一时刻可保存、加载的内容数据 |
| Facade API | 外观接口 | 面向业务开发者的上层 API,封装内部服务与命令 |
| Command / Mutation / Operation | 命令 / 数据变更 / 操作 | 分别编排业务动作、修改持久化数据、处理本地状态;正文会说明例外 |
| Scene / Layer / Viewport | 场景 / 图层 / 视口 | 分别组织画布对象、绘制层级和可见区域 |
| skeleton | 布局骨架 | 内容排版后的页面、行列与文字坐标 |
| AST | 抽象语法树 | 将公式表示为函数、运算和引用等结构 |
| OT | 操作变换 | 调整并发操作,使它们能在变化后的内容位置上应用 |
| Exchange | 保留原名 | Univer Pro 中负责 Office 文件与内部数据互转的模块 |
| Konva / Fabric.js / Babylon.js | 保留原名 | 已有的图形库与渲染引擎;Univer 官方列出的设计参考来源 |
| native binding | 原生绑定 | 让 JavaScript 调用平台原生模块的接口;Node 中常以 .node 文件加载 |
| changeset | 变更集 | 客户端向协作服务提交的一组内容操作 |
| revision | 修订版本号 | 协作服务为内容变更维护的连续版本,用于排序和发现遗漏 |
| Presence | 在线状态 | 当前会话的在线成员、光标和选区等临时协作信息 |
Univer is not built entirely from scratch. The open repository contains substantial editing and rendering implementations, while the full product also uses separately distributed Pro modules.
Univer 的模型、编辑命令、场景、布局和公式解释器都能在开源仓库中找到实现。实际执行又会调用 ot-json1、RBush 等库,并使用明确注明来源的 numfmt、linebreak、hyphen 派生代码。这些直接证据已足以排除“整个项目完全从零编写”的说法。
图形层要单独判断:官方渲染引擎架构设计明确说参考了 Konva、Fabric.js 和 Babylon.js;当前浏览器路径没有导入这些完整 SDK,而是在仓库内执行自己的场景与绘制代码。部分基础实现与上游高度对应,支持局部复用或改写的判断,但本次未追溯其引入历史,不能将所有对应都写成已确认的直接复制,更不能由此认定整个引擎是某个库的完整 fork。
另一个独立问题是源码范围。Office 文件转换、完整协同服务及若干高级功能分布在 Pro 模块中。本次还检查了公开的 Exchange 发布包,转换调用可以继续追到平台 .node 原生模块,但其内部解析算法与基础库并未在这个开源仓库公开。
版本基线为 2026 年 10 月 28 日默认分支 dev 的提交 b52b1ded90c25efb9befa60c4ff4e0452faa31e2,该快照的包版本为 1.2.0。下文源码链接固定到此提交;官网功能与服务端说明按同日在线文档理解。源码架构结论与文件兼容性承诺应分别评估。
概念与功能对应
| 名称 | 在 Univer 中的含义 | 与微软 Office 的关系 |
|---|---|---|
| Sheets | 工作簿、工作表、单元格、公式及表格编辑器 | 对应 Excel 一类的电子表格能力;XLS、XLSX 是需要转换的外部格式 |
| Docs | 富文本文档模型、排版与文档编辑器 | 对应 Word 一类的文档能力;DOC、DOCX 是外部格式 |
| Slides | 幻灯片页、图形、文本及演示文稿编辑器 | 对应 PowerPoint 一类的能力;PPT、PPTX 是外部格式 |
| PPT | 通常指 PowerPoint 文件或演示文稿 | 在这里不应单列为 Slides 之外的第四种编辑内核 |
内部实时编辑使用的是 Univer 自己的模型和 snapshot,而不是直接操作 XLSX、DOCX、PPTX 文件。文件转换负责把外部文件变成内部数据,再把编辑结果导出;渲染与交互负责让这些数据在屏幕上可见、可编辑。两者是不同的技术层。
实现责任与源码范围
“谁在执行”和“代码最初来自哪里”需要分别查证。下表按功能定位实际执行位置,后文再展开调用链:
| 功能 | 实际执行位置与复用 | 能从哪里读到实现 |
|---|---|---|
| 内容绘制 | Univer 的 Scene、Layer、Viewport 和绘制组件调用浏览器 Canvas 2D | 本仓库可读场景与绘制实现;图形库设计参考和源码对应见渲染章节 |
| Docs 编辑 | 本地 TextX 与 JSONX 组织操作;JSONX 实际调用 ot-json1,后者通过子类型回调本地 TextX | 编辑语义在本仓库,JSON OT 基础在外部包 |
| Docs 排版 | 本地 skeleton 安排行与页面;断行使用纳入源码的 linebreak fork,条件满足时使用 hyphen 派生代码断词 | 本仓库可读,包括明确标注来源的第三方代码 |
| Sheets 计算与显示 | 本地 Lexer、AST、Interpreter 执行公式;范围查询调用 RBush/KDBush;数字显示调用本地 numfmt 派生实现 | 公式流程与格式代码可读,部分基础数据结构来自外部包 |
| Slides 编辑 | 本地页面模型与对象适配器复用共享 Canvas 引擎,文字编辑再进入 Docs | 开源基础实现可读;Pro 增强层另行分发 |
| Office 文件转换 | exchange-node 的 JS 入口调用 exchange-node-binding,后者加载平台 .node 模块 | 公开发布包可读 JS 包装与接口;原生转换算法不在本仓库 |
| 完整多人协同 | Pro 的 Transport、Endpoint、Service 与数据库 Adapter 协作 | 官方文档和独立发布包可定位接口,不能由开源本地 OT 推出全部服务实现 |
因此,这个仓库足以解释主要编辑内核,也确实包含大量核心算法;解释完整 Univer 产品还需要检查独立模块。对于已经定位到、却未公开内部实现的原生转换模块,应明确停在该边界,不能补成“自研”或猜成某个 Office SDK。
总体架构
运行时与包的分层
flowchart TB
Host["业务应用与 Facade API<br/>React 工作台与控件"] --> Runtime["Univer 运行时<br/>插件容器"]
Runtime --> Core["core 模型与服务<br/>命令与历史"]
Core --> Sheets["Sheets<br/>工作簿与单元格"]
Core --> Docs["Docs<br/>文本与文档"]
Core --> Slides["Slides<br/>页面与元素"]
Sheets --> Formula[公式引擎]
Sheets --> Layout["各类型布局<br/>与渲染适配"]
Docs --> Layout
Slides --> Layout
Layout --> Render["共享 Canvas 引擎<br/>Scene / Layer / Viewport"]
| 主要目录或包 | 职责 |
|---|---|
packages/core | Univer 入口、基础模型、命令、撤销重做、插件、服务、Facade 基础 |
packages/engine-render | Canvas 封装、场景、图层、视口,以及文档和表格的布局与绘制 |
packages/engine-formula | 公式词法分析、语法树、解释执行、依赖管理、函数实现 |
packages/sheets 与 sheets-* | 表格逻辑及筛选、排序、校验、公式等扩展 |
packages/docs 与 docs-* | 文档编辑逻辑、历史、列表、链接、绘图等扩展 |
packages/slides 与 slides-ui | 开源演示文稿模型、元素适配与编辑界面 |
packages/ui 与 design | React 工作台、菜单、面板、对话框和设计组件 |
presets | 预先组合好的插件集合,简化集成 |
packages/rpc 与 rpc-node | 跨线程或进程通信、模型副本同步基础设施 |
Univer 创建依赖注入容器,并为 UNIVER_SHEET、UNIVER_DOC、UNIVER_SLIDE 注册 Workbook、DocumentDataModel、SlideDataModel。创建某类型的第一个 Unit 时,会启动该类型的插件。因此,一个 Unit 可以理解为有独立身份的一份工作簿、文档或演示文稿。
插件声明依赖后,PluginService 按依赖关系安排加载,并调用 Starting → Ready → Rendered → Steady 生命周期。插件可以注册服务、命令、渲染控制器和 UI。依赖注入由 @wendellhu/redi 提供;跨服务状态变化大量使用 RxJS。
源码入口:Unit 创建与模型注册、插件依赖与生命周期。
SDK 交付与文档保存
Basic editing can be delivered as a client-side SDK without a mandatory Univer server. 基础编辑器在浏览器中加载插件、创建 Unit 并处理编辑,文档数据可以由业务系统保存和加载,不强制使用 Univer 的服务端或官方存储。
例如,FWorkbook.save() 返回 IWorkbookData,FDocument.save() 返回 IDocumentData。它们调用本地 ResourceLoaderService.saveUnit,收集插件资源、克隆模型 snapshot 并返回对象;这个内置保存流程本身没有发起存储请求。业务应用再把数据写入自己的 API、数据库或浏览器存储,加载时交给 createWorkbook(data)、createDocument(data) 创建 Unit。图片等外部资源的地址与持久化也需要业务应用安排。
这里的“保存”得到的是 Univer 内部数据,不是 XLSX、DOCX 或 PPTX。使用官方 Office 导入导出方案时,需要 Exchange 转换能力;官方完整多人协同也需要相应服务。它们可以采用独立部署模块,因此需要后端能力与必须连接 Univer 托管服务仍是不同的条件。
源码:Workbook.save、Document.save、本地 saveUnit、加载 Workbook、加载 Document。
命令与数据变更
通用命令系统区分三种类型:
| 类型 | 设计职责 | 例子 |
|---|---|---|
| Command | 编排一次业务动作,生成正向变更和撤销所需的变更 | 删除行、设置单元格内容 |
| Mutation | 修改需要进入 snapshot 的数据,也是协同冲突处理的基本单位 | 写入单元格、插入行 |
| Operation | 按设计用于不进入 snapshot 的本地状态 | 滚动位置、侧栏状态 |
在 Sheets 的典型编辑流程中,Command 先读取旧值、生成逆向 Mutation,再执行正向 Mutation,将两组操作压入 UndoRedoService。撤销重做通过执行这些操作实现,不需要为每一步复制整个工作簿。统一入口也让 API 编辑、UI 编辑和变更监听能够使用同一条路径。
这套划分是架构规范,具体模块存在例外:当前开源 Slides 的部分 Operation 会直接写入页面元素,尚未完整沿用 Sheets、Docs 的持久化变更链路。不能由共享命令系统推导出三类编辑器的协同与历史能力完全相同。
渲染原理
Canvas 平台 API 与渲染库是不同层
这里的 Canvas 主要指浏览器提供的 HTMLCanvasElement 和 CanvasRenderingContext2D,不是一个名为 canvas 的前端 npm 渲染库。Univer 的 createCanvasElement() 调用 document.createElement('canvas'),Canvas 再调用 getContext('2d');UniverRenderingContext2D 包装这个原生 context,并把 fillText、drawImage、transform 等调用交给它执行。
所以底层关系是:Office 模型与布局 → Univer 的场景及绘制实现 → 浏览器 Canvas 2D → 浏览器自身的图形和字体实现。Univer 没有在这条链路中重新实现浏览器的文字栅格化与像素绘制,也不需要通过 Konva 的运行时才能调用 Canvas。
这条链路确定的是绘图后端。单凭使用 Canvas API,无法判断上层场景引擎是否独立编写;代码来源还要看明确声明、源码对应及历史记录。
源码:创建原生 Canvas、取得原生 2D context、context 包装、转发文本绘制。
Konva Fabric.js 与 Babylon.js 的具体关系
Univer Engineering Team 于 2025 年 6 月 28 日发表的工程文章明确写道:
Univer 的渲染引擎参考了 KonvaJs / FabricJs 以及 BabylonJs,基于 Canvas2D 实现。
这份说明还给出了具体的设计对应:Layer 参考 Konva 的分层设计;为表格冻结引入的 Viewport 参考 Babylon.js 的 Camera 概念,让同一 Scene 的不同区域通过多个窗口显示。参考 Babylon.js 的视口思想,并不意味着 Univer 使用它的 3D/WebGL 渲染后端。
依据:官方文章、固定版本的作者 日期与总述、Viewport 说明、Layer 说明。
源码对应也不限于类名或通用矩阵公式。下面这些片段包含相近的长注释、方法组织、中间变量和执行步骤:
| 基础实现 | 在 Univer 中做什么 | 可核对的上游对应 |
|---|---|---|
Transform | 组合、求逆、分解对象的二维变换;处理移动、缩放、旋转和斜切 | Univer 的 multiply、invert、decompose 与 Konva 的 Transform 高度对应;有 m 到 _m、rotation 到 angle 等适配 |
Path | 解析 SVG 风格的路径命令,并计算曲线几何与长度 | 与 Konva 的 parsePathData、calcLength 对应,包括命令切分流程和将贝塞尔曲线分成 100 段近似计算长度的步骤 |
_calcDimensionsMatrix 与 composeMatrix | 将 scale、flip、skew 等属性组合成变换矩阵 | 与 Fabric.js 的对应函数具有相近的整段注释、矩阵构造及条件顺序;Univer 改用自己的 Transform 对象组织运算 |
Vector2 | 为几何计算提供向量、插值等基础操作 | Clamp、Hermite 等注释和实现与 Babylon.js 对应,Lerp 注释中还可见相同的 adn 拼写 |
对照入口如下。上游提交用来固定比较对象,不表示已确认 Univer 当时导入的精确版本:
- Konva Transform:Univer 与 Konva。
- Konva Path:Univer 路径解析 与 Konva 路径解析;Univer 长度计算 与 Konva 长度计算。
- Fabric.js 矩阵组合:Univer 与 Fabric.js。
- Babylon.js 向量:Univer 与 Babylon.js;相同注释拼写见 Univer 与 Babylon.js。
这些较长的实现与注释对应,比“类名相同”更能支持局部复用或改写的判断;但这里的证据仍是源码对照,未查明每个片段的具体引入提交与传播路径。官方“参考”只能直接确认设计来源,不能替代这一层核查。现有证据也不足以把整个引擎归为某个库的完整 fork,或计算复用比例。Office 模型连接、布局、嵌套、视口和缓存机制仍要按本仓库的调用链分析。
直接依赖与内置代码需要分别检查
在本文固定快照中,engine-render 的外部生产依赖是 @floating-ui/dom、@floating-ui/utils、franc-min,另有 RxJS peer dependency,以及本仓库的 @univerjs/core。检查 manifest 与源码导入链,未发现运行时导入 Konva、Fabric.js、Babylon.js 或 PixiJS;实际绘制路径调用原生 Canvas 2D。已有的源码对应也解释了为什么“没有 npm 依赖”不能证明“没有使用它的代码”。
| 基础库或代码来源 | 在这里的职责 | 接入形式 |
|---|---|---|
| Floating UI | DOM 位置变化监测、浮层相关几何工具 | 有直接依赖;floating/util.ts 还明确注明部分方法复制自 autoUpdate |
franc-min | 文档断词流程中的语言识别 | 直接依赖,不负责场景绘制 |
| RxJS | 渲染状态与交互事件的通知 | peer dependency,不负责 Canvas 光栅化 |
eventlistener-polyfill 中的检测方法 | 检测事件监听的 passive 能力 | engine.ts 明确注明复制来源,不是完整库的运行时依赖 |
cjk-regex 的生成数据 | 为中文、日文、韩文等字符提供范围识别 | 正则与字符范围纳入源码,不是完整 npm 包的运行时依赖 |
jest-canvas-mock | 测试环境中的 Canvas 模拟 | devDependency,不是用户浏览器的绘图后端 |
canvas 这个 npm 包也要分清环境:该快照的 lockfile 在 jsdom 条目中列出了它的 optional peer 声明,这不能用来证明浏览器编辑器基于 Node 的 canvas 包渲染。浏览器路径仍由前面的 document.createElement('canvas') 与 getContext('2d') 调用确定。
来源:渲染包 manifest、Floating UI 复制说明、事件检测来源、CJK 数据来源、jsdom 的 optional peer。
React 外壳与 Canvas 编辑表面
React renders the workbench and controls; the content surface is drawn through Univer’s Canvas engine. 工作台、菜单和面板是 React 与 DOM,文档正文、表格网格和幻灯片主体由 Canvas 绘制。Canvas 最终调用浏览器 getContext('2d'),并处理设备像素比和尺寸;Engine 管理画布、事件和渲染循环。
引擎中几个概念各有职责:Scene 组织一个内容场景;Layer 管理绘制顺序、缓存和脏状态;Viewport 决定可见区域、滚动和裁剪;具体对象负责文本、表格、图片、矩形等绘制。配置缓存后,可以复用已有像素,在滚动时重绘暴露区域或失效部分。
这避免了为大量单元格创建 DOM 节点,但相应地,坐标命中、光标、选区、图形控制框和文本输入桥需要项目自己实现。实际速度仍受文档规模、复杂格式、公式、字体和缓存命中影响,Canvas 架构本身不构成性能数值保证。
源码:Canvas 2D 与像素比、渲染循环、图层缓存、React 工作台。
数据模型与布局骨架分离
模型回答“内容是什么”,布局骨架回答“内容应当画在哪里”。例如,一个段落的文本和样式属于模型,断成几行、落在哪一页、各字形的坐标属于 skeleton。表格中,行高、列宽及单元格数据属于模型;累计尺寸、可视范围、文字溢出和绘制缓存属于布局与渲染层。
这一分离使相同内容能以不同宿主配置呈现,也解释了 Docs 的文本能力为什么能复用于单元格和幻灯片。共享的是模型和排版基础,各宿主仍需处理自己的边界、对齐、旋转和交互。
Sheets 与 Excel 类功能
工作簿与稀疏单元格模型
IWorkbookData 保存工作簿标识、工作表映射、工作表顺序、样式池、计算设置及插件资源。IWorksheetData 保存行列数量、行高列宽、冻结、合并区域和单元格等。
单元格的关键字段为 v 原值、t 类型、s 样式或样式 ID、f 公式、p 富文本文档。cellData 采用按行号和列号索引的对象矩阵,Worksheet 将它封装为 ObjectMatrix;没有内容的格子无需逐一保存。
下面是零起始索引的简化结构,用于说明模型,不是完整初始化参数:
cellData: {
0: {
0: { v: 10 }, // A1
1: { f: '=A1*2', v: 20 }, // B1 公式与计算结果
},
}
源码:工作簿和工作表类型、单元格类型、ObjectMatrix。
网格布局与编辑
SheetSkeleton 将行高列宽转为累计几何信息,支持像素位置与行列索引之间的转换。SpreadsheetSkeleton 增加可视区域、字体、背景、边框和文本溢出等信息;Spreadsheet 再按视口绘制,利用缓存及滚动差分减少重复工作。冻结区域也由视口划分参与处理。
富文本单元格的 p 直接使用 IDocumentData。复杂文本可以走 DocumentDataModel → DocumentViewModel → DocumentSkeleton,复用 Docs 的测量、换行和布局;简单文本另有测量与缓存路径,并非每个格子都完整排版一份文档。
单元格编辑器和公式栏同样复用 Docs。用户完成输入后,编辑控制器把文档内容转回单元格数据,调用 SetRangeValuesCommand;后者执行 Mutation、收集自动行高等关联变更,并记录撤销操作。因此,表格中的“文字输入”与表格数据写入之间有明确的转换层。
源码:表格几何骨架、视口缓存绘制、单元格文档模型、编辑提交、设置范围命令。
公式引擎
The formula engine parses formulas into an AST and evaluates them through its own interpreter. engine-formula 的 Lexer、AST、依赖管理和函数实现均在本仓库;公式计算不依赖 Excel 进程、HyperFormula 或 JavaScript eval。其处理过程如下:
公式字符串
→ Lexer 与 LexerTreeBuilder 分析词法
→ AstTreeBuilder 构建语法树
→ 解析单元格与范围引用 建立依赖
→ 安排需要计算的节点
→ Interpreter 调用函数与运算实现
→ ValueObject 表示数字 字符串 错误 数组等结果
例如 A1 改变时,表格公式插件把变更范围记为 dirty range;计算触发服务合并待计算内容,依赖管理通过范围索引找到受影响的公式及其下游,再安排执行。这是按依赖传播的增量计算机制。
当前版本还用强连通分量把互相依赖的公式归为一组,为循环引用与迭代计算安排执行。不能把整个公式依赖结构一概描述为无环图。SUM 等函数本体也在仓库中实现,函数注册和扩展属于公式引擎的一部分。
公式引擎自研不意味着自动覆盖全部 Excel 行为。公式语义、数组公式、命名区域、跨表引用、数值精度以及 VBA 属于不同兼容维度,需按实际文件验证。
一个公式到底由谁计算和显示
以输入 =SUM(1,2),再设置 0.00 格式为例,计算值 3 与显示文本 3.00 来自两条职责不同的路径。下面是静态源码追踪示例,并非一次完整文件兼容性测试。
| 阶段 | 实际调用 | 实现责任 |
|---|---|---|
| 提交输入 | getCellDataByInput 将输入识别为公式,写入 cellData.f,再执行 SetRangeValuesCommand | 本仓库把 Docs 编辑内容转换成 Sheets 数据 |
| 解析与执行 | generateAstNode 调 Lexer 与 AstTreeBuilder;Interpreter 执行函数节点,调用注册的 Sum.calculate | 词法、语法、函数语义与执行流程在本仓库 |
| 普通累加 | Sum → ValueObject.plus → plusBy → math-kit.plus,后者执行 return a + b | 此例最终使用 JavaScript number 加法;不是把整个公式交给 decimal.js |
| 回填结果 | 计算结果 Mutation 经控制器转换为 SetRangeValuesMutation 写回单元格 | 本仓库的变更管线 |
| 生成显示文本 | 格式控制器 → getPatternPreviewIgnoreGeneral → numfmt.format → 本地 formatValue | 使用 core 内置、明确派生自 borgar/numfmt 3.2.6 的代码 |
这里的 numfmt 从 @univerjs/core 导出,源码就在 core/src/shared/numfmt,并非当前通过 npm 安装同名包来执行。但其文件和 LICENSE 明确写出上游来源,所以“在 core 里”也不意味着完全原创。公式数值与显示格式可以由不同来源的实现共同完成。
范围索引也有明确的外部调用:公式依赖管理使用 core 的 RTree,该封装实际创建 RBush/KDBush 并调用搜索;Univer 自己负责 dirty range 传播与执行安排。另一个 @flatten-js/interval-tree 用于倒排缓存已覆盖行段的查询,服务于条件比较等优化,不是整个公式调度器,简单的 SUM(1,2) 也不必经过它。
调用位置:输入转公式、构造 AST、基础加法、格式化调用、numfmt 来源、RBush/KDBush 封装、行段缓存索引。
Docs 与 Word 类功能
文本流与结构模型
The Docs model stores a linear text stream and range-based metadata rather than using the DOM as its source of truth. IDocumentBody 的核心是 dataStream:文本字符与结构控制符组成的线性流;textRuns 按范围记录字符样式,paragraphs、sectionBreaks、tables、customRanges 等记录结构和元数据。
例如段落和分节具有专用 token,表格也有开始、行、单元格、结束等标记。操作位置以字符串偏移为基础,部分接口明确采用 UTF-16 偏移,不能简单等同于用户肉眼看到的字符个数。
IDocumentData 在正文之外还可以包含文档样式、页眉页脚、绘图、列表、脚注尾注和插件资源。模型保留部分 DOCX 原始 XML 与往返转换元数据;保留某段原始 XML,与该内容已能排版或编辑是两件事。
从文档到页面坐标
DocumentViewModel 把线性文本流解析为分节、段落、表格等结构树。DocumentSkeleton 进行文本测量、断行、段落与页面布局,生成 Page → Section → Column → Line → Divide → Glyph 等几何结构。Documents 读取骨架,按页、行和字形组绘制,字体扩展最终调用 Canvas fillText。
浏览器仍负责底层字体测量与绘字;Univer 负责文档级的结构解释、换行和页面组织。这与直接交给浏览器 DOM 自动排版不同,也不意味着它从零实现了完整字体栅格化引擎。
断行算法还可再向下追:段落布局先执行 shaping,其中创建本地 LineBreaker 并循环取得 nextBreakPoint。这个目录的 README 明确说代码 fork 自 foliojs/linebreak,再改为 TypeScript。它提供可断行的位置,后续 lineBreaking、lineAdjustment 结合可用宽度安排实际行布局。自动断词仅在配置开启、语言已识别且相应词典已加载等条件满足时进入 LineBreakerHyphenEnhancer,调用本地 _hyphen.hyphenate;该目录明确注明部分代码改自 ytiurin/hyphen。两者都有直接来源声明,证据强于图形层的源码相似对照。
当前 DocumentFlavor 包含 TRADITIONAL、MODERN、DRAWINGML:Traditional 面向纸张分页文档;Modern 使用连续布局;DrawingML 为形状和幻灯片文本提供宿主语义。代码还包含增量布局、旧任务取消和部分结果发布,因而不能把它描述为每次输入都必然全量排版。
源码:解析文本流、增量排版与连续模式、Canvas 文本绘制、DocumentFlavor。
基础算法调用:段落布局阶段、创建 LineBreaker 与断词条件、断行位置生成、断词调用。
输入法与选区
Canvas 本身不提供完整文本输入语义。当前实现创建了一个文本和原生光标透明、被 1px 容器裁剪的 contentEditable div,接收 input、键盘及 composition 事件,再由控制器转换成编辑命令。IME 有独立的输入控制器;这里使用的不是 textarea。
可见的光标和选区由项目维护,并借助布局骨架将屏幕坐标映射为文本偏移。必要时再与 DOM selection 同步。因此,用户看见的是 Canvas 文字,浏览器原生可编辑元素承担输入接入,两者相互配合。
编辑操作与 OT
flowchart TB
Input[输入事件] --> Command[InsertTextCommand]
Command --> Ops[TextX 与 JSONX 操作]
Ops --> Mutation[RichTextEditingMutation]
Mutation --> Model[DocumentDataModel]
Model --> Layout[布局与 Canvas 更新]
Mutation --> History[逆操作与历史合并]
TextX 是仓库实现的富文本操作类型,提供 insert、retain、delete 以及操作应用、合并、变换和求逆。JSONX 则包装第三方 ot-json1,将 TextX 注册为子类型,用来处理整份文档 JSON 中的操作。
以插入文字为例,InsertTextCommand 构造 TextX 的 retain/insert,再经 JSONX.editOp 实际调用第三方的 json1.editOp。Mutation 将操作交给 DocumentDataModel.apply,后者调用 JSONX.apply,最终进入 json1.type.apply。由于 JSONX 已用 json1.type.registerSubtype(TextX) 注册本地子类型,正文富文本的应用又回到本地 TextX。也就是说,外部库确实参与执行,但文档编辑语义并非全部由外部库提供。
历史服务可把连续编辑合并,并保存正向与逆向 Mutation。OT 原语让操作具备相互变换的基础,但联网协同还需要会话、服务端权威版本、操作确认、广播和持久化,不能仅因存在 transform 就认定开源仓库附带完整协同系统。
源码:插入文本操作、实际应用到模型、JSONX 与 ot-json1、历史合并。
外部调用与注册:json1.editOp 与 TextX 注册、TextX.apply。
Slides 与 PPT 类功能
页面与元素
ISlideData 保存演示文稿标识、标题、页面大小等,正文用 pages 字典保存页面,用 pageOrder 保存顺序。每页再保存背景和 pageElements;元素具有位置、尺寸、旋转、缩放、翻转、层级,以及图形、图片、富文本、文档或表格等载荷。
渲染控制器为每页创建独立 Scene。ObjectProvider 通过适配器将数据变成引擎的 Rect、Circle、RichText、Documents、Spreadsheet 等对象,再挂到场景中。切页激活对应子场景,缩略图复用相同页面场景缩放绘制。
这是一条自有模型到自有渲染引擎的链路,不是调用 PptxGenJS 生成文件后再当作编辑器,也不是把 Reveal.js 网页幻灯片作为内核。
源码:Slides 数据模型、页面场景创建、对象适配注册表。
文本和图形编辑
双击文字时,Slides 启动内部的 Docs 编辑单元,复用文档输入、选区和排版,结束后把结果写回幻灯片元素。嵌入文档和表格的适配器,也分别调用自家的文档、表格模型和渲染组件;存在表格适配器不等于已经提供完整的嵌入式 Sheets 编辑体验。
图片和图形使用共享渲染引擎的对象变换能力,Transformer 提供选择及移动、缩放、旋转等交互。开源形状适配器当前明确处理矩形、圆角矩形和椭圆等基础类型。
源码:文本编辑桥、内部 Docs 单元、文档适配器、基础形状适配。
开源基础层的边界
当前 README 将 Slides 分为开源模型与 UI 包,以及 Pro 模型、UI、文件转换、图表和表格等增强层。但公开基础实现也不应等同于完整 PowerPoint:
master、layout等 schema 字段说明模型表达了相关概念,不能单靠字段证明完整母版编辑、继承解析或 PowerPoint 动画兼容。UpdateSlideElementOperation直接合并并更新页面元素,这条路径不同于成熟的 Mutation 历史编排。SlideDataModel.getRev()恒返回 0,incrementRev、setRev没有更新逻辑,源码明确保留尚未实现 Slides 协同的说明。这一结论针对该开源类,不代表 Pro 产品的全部能力。
源码:元素更新操作、revision 接口。
自研部分与第三方复用
| 能力 | 实现判断 | 可核实的复用 |
|---|---|---|
| Office 编辑器主体 | 模型、命令、场景与编辑流程在仓库内实现 | 下列通用库与明确注明来源的代码 |
| Canvas 场景引擎 | 仓库内维护 Engine、Scene、Layer、Viewport 及渲染组件;后端调用原生 Canvas 2D | 官方确认参考 Konva、Fabric.js、Babylon.js;局部基础代码高度对应,具体引入历史未核实 |
| UI 外壳 | 自有工作台与设计组件 | React、ReactDOM、Radix UI、Floating UI 等 |
| 插件运行时 | 自有插件管理、生命周期、服务约定 | redi 依赖注入、RxJS 状态流 |
| 表格公式 | 自有 Lexer、AST、Interpreter、依赖与函数体系 | RBush/KDBush 范围查询、interval-tree 缓存索引;decimal.js 用于部分数值能力 |
| 文档操作 | 自有 TextX 与文档编辑语义 | JSONX 直接使用 ot-json1 的 JSON OT |
| 文本断行与断词 | 集成后服务于自有文档布局 | 断行 fork 自 foliojs/linebreak,断词部分改自 ytiurin/hyphen |
| 数字与日期格式 | 仓库内有实现及扩展 | 源码明确派生自 MIT 的 numfmt 3.2.6 |
| Office 格式转换 | 独立 Pro JS 包装调用平台原生模块 | 可定位 native binding;原生解析器内部依赖未公开确认 |
单看 package.json 会漏掉直接纳入源码的代码;也不应把“有 decimal.js 依赖”理解为所有公式基本运算都交给它,当前 math-kit 的基础算术仍直接使用 JavaScript number。
本文据此区分证据强度:import 与具体函数调用确认运行时依赖;fork from、Derived from、copied from 等声明确认相应代码的复用来源;官方“参考”确认设计参考;高度源码对应支持进一步的来源判断,却不能单独确定引入版本和完整历史。这些情况不能统称为“参考”,也不能因为未导入完整 SDK 就推导出“从零实现”。
来源:core 依赖、公式引擎依赖、断行代码来源、断词代码来源、numfmt 来源、基础算术实现。
Office 文件转换与商业能力
开源与 Pro 的分界
公开仓库使用 Apache 2.0,基础 SDK 可以独立使用;Pro 是可选扩展,产品家族中的商业能力仍适用各自的许可。
| 类型 | 开源仓库的主要能力 | README 列出的部分 Pro 扩展 |
|---|---|---|
| Sheets | 表格编辑、公式、格式、筛选排序、校验、条件格式、评论、表格与绘图集成 | 协同、编辑历史、导入导出、打印、图表、透视表、增强计算等 |
| Docs | 文档模型、编辑 UI、列表、链接、评论与绘图集成 | 协同、导入导出、打印、增强表格列表、分栏与形状等 |
| Slides | 演示文稿模型与 UI 包 | Pro 模型与 UI、导入导出、图表和表格等 |
| 运行时 | Node headless、Worker 与 RPC 基础 | 协同服务、SSR、计算委托及变更重放等 |
表中是公开能力划分,不是逐个格式或函数的测试清单。例如排版基础中存在 Column 结构,并不能据此认定所有产品级分栏编辑功能都属于开源 UI。
转换链路
flowchart TB
File[Office 文件] --> Import[Pro Exchange 导入]
Import --> Data[Univer 模型与 snapshot]
Data --> Editor[浏览器编辑器]
Editor --> Updated[更新后的 snapshot]
Updated --> Export[Pro Exchange 导出]
Export --> Result[Office 文件]
当前官方 Server SDK 使用 @univerjs-pro/exchange-node 提供 importFile()、exportToFile()。转换既可集成在自己的 Node.js 进程,也可由远程服务承接;单独文件转换不要求接入 AI SDK 或多人协同服务。浏览器侧转换 API 与后端转换模块也应分开理解。
从公开 JS 入口追到原生模块
本次检查了公开发布的 @univerjs-pro/exchange-node@1.2.0 和它依赖的 @univerjs-pro/exchange-node-binding@1.0.4,不只停留在官网的模块名称。可读的 JS 给出了如下链路:
importFile(path)
→ importFileToSnapshot 读取文件 Buffer
→ importSnapshot 处理格式和选项
→ exchange-node-binding.exchangeImportToSnapshot
→ 平台 .node 原生模块
→ JS 恢复 snapshot
→ snapshotToMemory 转为 Univer 内存模型
| 边界 | 发布包中的实际行为 |
|---|---|
| Node JS → binding | loadNativeBinding() 使用 createRequire 加载 @univerjs-pro/exchange-node-binding |
| binding → 平台模块 | 根据 process.platform、process.arch 选择目标,加载本地 .node 或对应平台 npm 包;例如 Linux x64 GNU 的入口为 univer-exchange-node.linux-x64-gnu.node |
| 原生模块 → snapshot | exchangeImportToSnapshot 返回 snapshot JSON、元数据及表格块;JS 恢复相应数据 |
| snapshot → 内存模型 | 调用 @univerjs-pro/collaboration 中的 snapshot 转换工具;使用这些工具不等于必须启动多人协同服务 |
| 导出 | memoryToSnapshot → exchangeExportSnapshot → 输出 Buffer,exportToFile 再写文件 |
binding 的类型文件注明由 NAPI-RS 生成,能确认原生接口的绑定工具。可读 JS 直接调用本地原生模块,未把转换转发成 HTTP 请求。但这些事实无法确定原生模块内部使用的语言、OOXML 解析器或其他 SDK;NAPI-RS 的存在也不能证明所有转换代码都是 Rust,更不能证明完全原创。
本次核查读取了公开包的 JS、类型与元数据,没有执行或反编译平台二进制。原生转换算法不在 dream-num/univer 仓库内,这是当前能够明确定位的实现边界。公开可下载的 Pro 发布包也不等于其全部内部实现按 Apache 2.0 开源。
可复核的固定版本:Exchange 包元数据、Exchange JS 入口、binding loader、binding 类型、Linux 平台包元数据。JS 入口中可直接搜索 importSnapshot、exchangeImportToSnapshot、exchangeExportSnapshot 核对调用。
官网格式声明与发布包入口的差异
exchange-node@1.2.0 的 FORMAT_BY_EXTENSION 和 ExchangeFormat 只列出以下八种输入格式;导出列来自该包 README 的声明,未在本次逐个执行文件转换:
| 内容类型 | 发布包默认按扩展名识别的输入 | 发布包 README 声明的输出 |
|---|---|---|
| 电子表格 | XLS、XLSX、CSV、TSV | XLSX、CSV、TSV |
| 文档 | DOC、DOCX | DOCX |
| 演示文稿 | PPT、PPTX | PPTX |
同日官网 Node 转换页还列出 XLSM、PPTM、PPSX、PPSM、POTX,比该发布包的默认扩展名表更宽。按可读的 resolveFormat 逻辑,仅以这些扩展名调用且未显式传入 format 时,会在 JS 参数处理阶段抛出 UNSUPPORTED_FORMAT,尚未进入原生转换。
若显式传入 format,代码会跳过文件名推断;原生模块是否可按指定格式接受更广的输入,本次未执行验证,不能据默认扩展名表断言全部拒绝。官网声明、具体版本入口和真实文件转换结果,应作为三类不同证据。支持含宏格式作为输入也不等于执行 VBA。
浏览器侧 API 还有自己的格式范围,不能直接套用 Node 模块的表。官方 Web SDK 文档说明,1.2.0 起移除了内建导入导出菜单交互,但保留服务和 Facade,业务应用需要组织自己的入口。文件能打开、内容能编辑、导出后保留原貌,仍是三个需要分别验证的目标。
官方资料:Server 架构、Node 文件转换与格式表、Sheets 浏览器转换、Docs 浏览器转换、Slides 浏览器转换。
Worker 服务端与协同
Worker 的两条路径
Sheets 支持把模型与公式引擎实例放进 Web Worker。主线程发送 snapshot 创建计算副本,之后通过 RPC 同步相关 Mutation,计算结果再回送。Worker preset 注册的是数据逻辑、公式和通信插件,不意味着整个编辑 UI 都被搬到 Worker。
Docs 则有独立的 layout worker:根据 snapshot 创建文档模型及布局会话,处理排版并返回结果,要求相应的 OffscreenCanvas 文本测量能力。这与 Sheets 的计算副本协议不同。是否启用这些路径取决于插件和配置,不能笼统表述为“所有编辑默认都在 Worker”。
源码:Sheets Worker preset、snapshot 与 Mutation 同步、Docs 排版 Worker。
Node headless 与多人协同
同构设计要求将模型、Command、Mutation 等逻辑与 React、Canvas、菜单等浏览器依赖分开。Facade 也随插件划分,使同一套数据处理 API 能用于浏览器与 Node。这为批量修改工作簿、公式计算和自动化提供了基础;浏览器画面、Office 文件转换和完整协同后端仍需各自的模块。
团队协作方案
The official realtime-collaboration solution requires a backend, and its Server SDK can run in your own Node.js service. 基础编辑不强制依赖 Univer 服务端;官方完整多人协作方案则使用 Pro 协作客户端和服务端模块,可以自托管。业务系统继续管理账号、角色、文档目录和分享规则。
若自行建设协作系统,开源的 TextX、JSONX 和 Mutation 可以作为基础,但还需要设计协议、版本、并发处理、重试去重、权限、持久化和恢复,并覆盖自定义插件的变更语义。这是另外一项系统工程,也不表示任意自建后端都能直接兼容 Pro 客户端。
客户端与服务端怎么组成
| 位置 | 当前官方模块 | 职责 |
|---|---|---|
| 浏览器 | collaboration、collaboration-client、collaboration-client-ui | 加载同一个 Unit、提交变更、同步远端内容及显示协作状态 |
| Node 接入 | collaboration-transport-node | 承接 HTTP 与 WebSocket,将认证后的上下文交给后续模块 |
| 会话层 | collaboration-endpoint | Session、Room、Presence、确认与广播 |
| 内容层 | collaboration-service | 权威 Unit、OT、revision、变更提交和持久化协调 |
| 数据层 | Memory、SQLite 或自定义 Database Adapter | 保存 snapshot、changeset、revision 等协作数据 |
表中协作包使用 @univerjs-pro/ 命名空间。最小服务由 Transport、Endpoint、Service 和一个 Database Adapter 组成,不需要把整个业务后端改成 Univer 的应用服务器。官方 Node 模块可嵌入现有进程,也可以作为独立服务与业务系统对接。
接入时先由后端创建并持久化 Unit,再让各浏览器加载同一个 unitId。当前客户端提供 loadSheetAsync、loadDocAsync、loadSlideAsync;前端设置的 userID、姓名和头像用于用户呈现,不能直接作为服务端可信身份。协作连接也不是一个 UI 插件的 serverurl 参数:当前客户端分别配置 snapshot、授权、changeset 提交、WebSocket 和 session ticket 的地址。
依据:Quick Start、浏览器接入、Docs 协作、Slides 协作。当前 Slides 的 Pro 协作路径,应与前文开源 SlideDataModel 的 revision 占位实现分开评估。
变更怎样同步和保存
当前方案基于 OT 与服务端权威 revision。内容提交通过 HTTP 接口完成;WebSocket 负责会话、在线状态、确认和广播,不能把所有编辑笼统描述为经 WebSocket 提交。
flowchart TB
Client["协作客户端<br/>changeset 与基础 revision"] -->|HTTP 提交| Entry["Transport / Endpoint<br/>可信身份与协议处理"]
Entry --> Service["Collaboration Service<br/>权限校验与 OT"]
Service --> DB["Database Adapter<br/>原子提交变更与 revision"]
DB --> Result[Service 返回权威结果]
Result --> Broadcast["Endpoint<br/>确认与房间广播"]
Broadcast -->|WebSocket| Views[客户端确认与同步]
客户端的提交标识 sid、reqId 用于重试去重;服务端维护连续 revision,客户端据此发现缺失变更并恢复同步。Presence 是会话层临时状态,与持久化文档内容属于不同的数据。开源的本地 Undo/Redo、Worker 副本同步,以及这套多人协作协议也各有职责,不能把它们混称为同一种同步,更不应把该 OT 方案写成 Yjs CRDT。
协作启用后,应以服务端的变更提交与 revision 为内容持久化入口。多个浏览器各自定时保存整份 snapshot 并覆盖同一个数据库记录,无法替代这条并发处理链路。
团队权限 评论与历史
开源代码已有权限点和命令拦截:Sheets 有工作簿、工作表和范围保护;Docs 有文档及部分对象的编辑权限。它们帮助界面和本地命令遵守权限,但默认 IAuthzIoService 绑定的本地实现明确是 mock,并注明不能用于生产授权。
业务集成需要在服务端从自己的 cookie、token 或 session 得到可信 userID,分别检查内容读取、加入 Unit、提交变更和其他资源操作。仅设置前端只读,或者仅禁止加入实时房间,都不能覆盖 HTTP 内容读取与提交入口。身份展示、客户端编辑控制和服务端授权是三项不同职责。
评论和历史也需分别接入:评论模型、UI 和可替换的 IThreadCommentDataSource 在开源仓库,业务可以实现自己的评论后端;官方共享数据源和评论服务另有模块。本地 Undo/Redo 则不等于可持久化、按版本查看的团队编辑历史。采用自定义内容插件时,历史 viewer 和其他客户端也需要相应插件,才能正确呈现内容。
来源:服务端身份与授权、默认授权 mock、评论数据源接口、Docs 评论、Docs 编辑历史。
细粒度权限还有服务端接入点:启用 enableUnitPermissionAnalysis 后,可在 commitChangeset 检查 requiredUnitPermissions,由业务 ACL 决定是否允许整组变更。工作表或范围保护中的对象标识是保护规则的 permissionId,不能直接当作工作表 ID 或 A1 地址使用。官方有固定版本的对象权限示例,其落库前校验展示了这条集成路径。
持久化 部署与断线恢复
Memory Adapter 适合临时验证,进程退出后数据丢失;SQLite 提供持久化接入,也可实现 IDatabaseAdapter 对接自己的数据库。自定义 Adapter 需要满足 revision 的比较并交换、提交幂等、连续变更和原子写入等契约,不能只实现普通 JSON 的读取与覆盖。snapshot 与后续已确认 changesets 共同支持内容恢复,不能把最近一次 snapshot 写入时间直接当作所有编辑的确认状态。
官方提供SQLite 接入示例和PostgreSQL Adapter 示例。这些是可读的接入路径,本次没有将其部署为生产服务或做容量验证。
扩到多个协作节点时,除了共享内容数据库,还需要共享 pub/sub 与一次性 session ticket 存储。否则,一个节点签发的票据未必能被另一个节点消费,在线会话也不会仅因共用数据库就收到实时通知。官方 Redis 模块和多节点示例补齐这些连接;后台任务在另一 Service 实例直接写数据时,同样需要安排通知传播。
collaboration-client@1.2.0 的 enableOfflineEditing 默认是 false。当前客户端已有排队、等待确认、离线等状态,以及本地缓存和恢复接口;启用断线编辑后,产品仍需处理未确认提交、重试、冲突和权限拒绝,不能承诺任意离线修改都会无损自动合并。Presence 不写入内容数据库,也不增加内容 revision,不能用在线光标或在线人数判断内容是否已经保存。
以上是官方文档、公开类型和示例能够确认的集成机制,尚未进行双客户端并发、断线恢复或多节点压测。自托管也不等于免 Pro 授权;许可配置和完全断外网部署条件需分别核实,本次没有审计完整许可校验路径。
资料:Database Adapter 契约、部署说明、浏览器恢复接口、客户端配置、Pro 授权、固定版本 Service 类型、固定版本 Endpoint 类型。
自定义与二次开发
Univer 的扩展范围包括业务 UI、命令、公式、单元格绘制和插件数据。多数基础扩展点就在开源包中,不需要先购买 Pro 才能编写自己的业务插件。新增功能能否保存、撤销、跨客户端同步和导出 Office 文件,则需要逐项实现或核查。
可用的扩展接口
| 需求 | 扩展方式 | 需要分清的边界 |
|---|---|---|
| 增加业务操作 | 插件注册服务与 Command/Mutation,Facade 调用同一命令管线 | 数据修改、逆操作和协作处理需要完整设计,不能只直接改模型对象 |
| 定制工作台 | createMenu、updateMenuConfig、registerComponent、openSidebar、registerUIPart | 可加菜单、React 面板及工作台插槽;不要求修改 Canvas 引擎 |
| 响应用户操作 | Facade addEvent 订阅命令、单元格和选区等事件 | Sheets 和 Docs 的事件面不同;单元格点击也不等于值变化 |
| 接入业务公式 | getFormula().registerFunction、registerAsyncFunction | 注册的是计算运行时回调,不是随 snapshot 分发的脚本 |
| 在单元格中画业务状态 | registerCellCustomRender 与 ICellCustomRender.drawWith | 在 Canvas 上绘制,可处理命中与指针事件,不是为每个格子创建 React DOM |
| 添加复杂交互组件 | FRange.attachPopup、attachRangePopup | DOM 组件锚定到单元格或范围;浮层本身不构成持久化的业务数据 |
| 保存插件业务模型 | registerPluginResource 的序列化、加载和卸载钩子 | 数据进入 snapshot.resources,但不会自动获得并发变换与文件转换语义 |
| 增加 Docs 正文结构 | 文档模型扩展字段配合编辑、布局和渲染插件 | 自定义正文还需覆盖复制粘贴、历史、协作及导出降级行为 |
调用入口:自定义公式、自定义单元格绘制、Canvas 回调接口、DOM popup、资源钩子、Docs 扩展字段。
从业务面板接到编辑管线
例如要做“选中单元格后,在侧栏核对业务数据”的功能,可以注册自己的 React 组件,使用 openSidebar 挂载;Sheets 的 SelectionChanged、CellClicked 事件提供选区或坐标,业务再通过 range API 读取数据。提交核对结果时,复用已有 Facade 或 SetRangeValuesCommand,让写值进入既有 Mutation 和撤销管线,而不是直接修改快照引用。
确实需要新模型状态时,再定义自有 Command/Mutation、逆操作和资源序列化。ICommand 使用的注册标识是 id;注册一个 Command 本身不会自动生成 Undo。若要协作,客户端、服务端和历史 viewer 等运行端还需要理解相关 Mutation 及冲突处理。React state、任意闭包或服务对象不会因为插件注册而自动同步给其他用户。
DI 的 override 可以替换抽象服务;Facade 的 extend 配合 TypeScript 接口增强可以提供自己的业务 API。这些适合封装领域逻辑,但需要在相关服务实例化前安排好替换与插件加载。仅补充 TypeScript 类型,不会产生运行时实现。
界面与业务逻辑也应分开:菜单、React、DOM 和 Canvas 留在 UI 插件;模型和命令不直接读取选区等 UI 状态,才能在 Node 或 Worker 复用。优先依赖公开文档与包入口暴露的接口;深导入 controller、下划线方法或内部模型,会增加升级时的适配工作,不能与稳定 Facade 视为同一种接入。
源码:菜单与面板 Facade、组件注册与工作台插槽、Sheets 事件接口、Command 标识与参数、Facade.extend、API 分级。
自定义数据与跨端执行的限制
ICellData.custom 和 Facade 的自定义元数据接口确实存在,但当前实现会提示不建议外部使用,SetRangeCustomMetadataCommand 还明确注明不支持 Undo/Redo。需要长期维护的业务模型,应先评估正式资源钩子与自定义命令方案,不能假定所有扩展字段都具有标准编辑的历史行为。
自定义公式同样要考虑计算发生在哪里。当前 RemoteRegisterFunctionService 明确拒绝把函数经 RPC 反序列化注册,原因是这种做法不安全。因此,主线程注册一个闭包,不会自动在 Worker 或协作服务端部署同一实现;实际计算端需要受控地注册对应代码。
异步公式 API 证明引擎能够等待 Promise,并不保证多个客户端得到相同结果。回调若读取时间、随机数或外部接口,团队集成应统一函数版本和数据输入,必要时采用明确的权威计算来源。这是应用侧设计要求,不是已验证的 Pro 默认行为。
屏幕绘制扩展也不会自动变成导出内容:SheetExtension.copyForPrinting() 默认返回 null,打印需要单独适配;自定义模型进入 snapshot,也不保证 Exchange 会把它映射为相应 Office 结构。应分别检查编辑画面、历史查看、打印与文件往返。
源码:元数据接口警告、元数据命令的历史限制、远端函数注册限制。
打印扩展:SheetExtension 默认行为。
架构判断与选型验证
Univer 让不同内容类型复用同一套运行时。Sheets、Docs 和 Slides 共享身份与插件机制、服务、渲染基础,以及部分文本和绘图能力。Docs/Sheets 的 Drawing 插件还共用基础绘图模型,再分别处理文档锚点和表格锚点;图形随行列或段落变化的行为,需要宿主自己的适配逻辑。
这种架构适合需要深度嵌入、扩展命令或建立结构化自动化接口的产品。代价是需要理解插件组合、内部模型和各模块的功能边界;自有 Canvas 文本系统还需要关注输入法、字体、无障碍与排版回归。不能用某一个模块的能力水平代表整个 SDK。
当前快照下,Sheets 的模型、网格、公式与变更管线可在源码中完整追踪;Docs 已包含分页、连续布局、表格及复杂文本机制;开源 Slides 提供基础页面和元素编辑,但 revision 与变更路径显示出更明确的限制。需要 PPT、Word、Excel 文件兼容时,还应将 Pro 转换和目标文件样本纳入评估。
进入实际项目之前,建议用真实材料验证以下内容:
- 表格计算:关键公式、循环引用、大范围依赖、格式和数值结果是否满足业务要求。
- 文档排版:中文输入、字体替换、分页、页眉页脚、表格及复杂段落是否稳定。
- 演示文稿:母版、图表、嵌入内容、动画与导出保真分别达到什么程度。
- 运行与集成:目标设备上的加载和编辑表现、Worker 配置,以及实际需要的 Pro 模块和部署方式。
- 团队协作:两个独立会话的同步、服务重启后的持久化、读取与提交的服务端权限、断线恢复,以及多节点之间的通知。
- 自定义扩展:相同插件在客户端、Worker、协作服务端及历史 viewer 中的行为,撤销重做、数据保存、打印与 Office 导出的覆盖范围。
继续读源码时,可依次从 core/src/univer.ts、core 的模型与命令系统、各类型的 skeleton 和渲染组件,再进入 UI 控制器。这个顺序能先建立数据和状态变化的理解,再解释屏幕上的编辑行为。