无头与服务端计算
在 Node.js 中读写内容,结合 Rust 预计算与数组展开,为应用和 Agent 提供结构化与视觉结果。
Headless Univer 是 Univer 的内容运行时,不包含可交互的编辑器界面。它与浏览器编辑器共用同一套内容模型、命令、计算和 Facade API。应用可以在 Node.js 中运行它来处理内容,也可以在浏览器中运行它来执行不需要界面的任务。它具备哪些能力,取决于注册了哪些产品和功能插件。
本页介绍的 JavaScript/TypeScript 内容运行时与 univer-rs 是两套彼此独立的实现。后者负责服务端计算和文件转换,可以基于同一份快照与 Headless 工作流配合使用。
Headless 能做什么
- 读写内容和结构。创建或加载 Univer 快照,使用 Facade API 读写单元格、段落、页面、图形对象或记录,然后保存更新后的快照。批量处理、数据生成、内容检查和 Agent 自动化均以这套能力为基础。
- 运行已注册的业务逻辑。运行时支持公式计算、排序、筛选、数据验证和透视表插件,也可以修改图片、图表、形状和评论等资源。可执行的操作取决于注册的产品和功能插件及其依赖。
- 连接其他服务。接入 Node.js 协同客户端后,可以加载协同 Unit、提交修改并等待同步。将 Server SDK 的转换模块与运行时结合,可以导入和导出 Office 文件。
Headless 不提供编辑器界面,包括菜单、工具栏、弹窗、鼠标键盘交互、截图和打印。它也不自带持久化、用户认证、协同服务器和文件转换能力。save() 返回的是 Univer 快照,不会写入数据库,也不会导出 XLSX、DOCX 或 PDF。截图和视觉布局检查需要单独接入渲染运行时,因为无界面浏览器仍然运行渲染层。
哪些包属于 Headless 范畴
按需选择内容层的包,然后注册它们对应的产品插件和依赖。使用 Pro 功能还需要配置相应的许可证。
内容模型
这些包提供实例、内容模型、命令和基础内容操作。
@univerjs/core@univerjs/sheets@univerjs/docs
公式与数字格式
这些包提供公式执行、表格公式接入和数字格式。根据所需功能选择开源引擎或 Pro 引擎。
@univerjs/engine-formula@univerjs/sheets-formula@univerjs/sheets-numfmt@univerjs-pro/engine-formula
表格数据与规则
表格数据和规则操作可以正常运行,但运行时不提供通常配套的面板和可视交互。数据验证还需要引入 @univerjs/data-validation。
@univerjs/sheets-filter@univerjs/sheets-sort@univerjs/sheets-conditional-formatting@univerjs/sheets-data-validation@univerjs/sheets-table@univerjs/sheets-hyper-link@univerjs/sheets-note
图片、链接与评论
这些包提供图片、链接和评论的模型、资源和命令。显示、上传和外部数据源按需单独接入。
@univerjs/drawing@univerjs/sheets-drawing@univerjs/docs-drawing@univerjs/docs-hyper-link@univerjs/thread-comment@univerjs/sheets-thread-comment@univerjs/docs-thread-comment
表格高级功能
这些包提供透视表、图表、形状、迷你图、分组和切片器的内容与计算逻辑。图形相关的依赖可能还包括 @univerjs-pro/engine-chart 和 @univerjs-pro/engine-shape。
@univerjs-pro/sheets-pivot@univerjs-pro/sheets-chart@univerjs-pro/sheets-shape@univerjs-pro/sheets-sparkline@univerjs-pro/sheets-outline@univerjs-pro/sheets-slicer
文档扩展
文档块、表格、分栏、公式和形状支持内容操作,但不提供编辑器控件。
@univerjs-pro/docs-callout@univerjs-pro/docs-code@univerjs-pro/docs-list@univerjs-pro/docs-quote@univerjs-pro/docs-table@univerjs-pro/docs-column@univerjs-pro/docs-latex@univerjs-pro/docs-formula@univerjs-pro/docs-shape
其他产品模型
这些包提供其他产品的模型和命令。pdfs-editor 配置 PDF 编辑器的生命周期和协同接入;包名中包含 editor 不代表提供界面。各产品可用的 API 不同。
@univerjs-pro/slides@univerjs-pro/bases@univerjs-pro/boards@univerjs-pro/pdfs@univerjs-pro/pdfs-editor
网络、计算进程与协同
基础设施按需引入。@univerjs/network 和 @univerjs/rpc-node 提供网络能力和 Node.js 计算进程,@univerjs-pro/license 负责许可证接入。@univerjs-pro/collaboration、@univerjs-pro/collaboration-client 和 @univerjs-pro/collaboration-client-node 共同构成 Headless 协同客户端,不是协同服务器。处理本地快照不需要接入协同服务。
哪些包不属于纯内容运行时
@univerjs/ui、@univerjs/design,以及产品或功能的*-ui包(例如@univerjs/sheets-ui、@univerjs/docs-ui、@univerjs-pro/slides-ui)提供界面、渲染接入或交互能力,不应加入仅处理内容的 Node.js 配置。@univerjs/sheets-find-replace和@univerjs/sheets-crosshair-highlight没有-ui后缀,但依赖@univerjs/sheets-ui,因此不能仅凭包名认定它们是 Headless 插件。@univerjs/preset-sheets-core和@univerjs/preset-docs-core这两个默认预设会注册 UI 插件,不是 Node.js Headless 预设。这类场景应使用插件模式,明确选择内容层的依赖。
@univerjs/engine-render 需要单独说明。 当前的 Node.js 示例会注册它,用于提供渲染管理等共享依赖。注册插件并不创建 Canvas,也不挂载编辑器。它可以出现在 Headless 组合中,但绘制、字体测量和截图 API 仍然需要合适的渲染环境。因此,不能认为该包的所有 API 都能在纯 Node.js 中使用。
Facade 是操作 API,不是运行环境的适配层。 对于所用的内容插件,导入其 /facade 扩展,并注册提供相应能力的插件。@univerjs/ui/facade、@univerjs/sheets-ui/facade 这类 UI 扩展仍然需要 UI,它们提供的菜单、滚动和选择区交互同样如此。判断时应检查插件依赖和实际调用路径,不能只看包名,也不能只看是否存在 Facade API。
可运行的插件组合见 Sheets Headless 入门和 Docs Headless 入门。
前端即时计算,服务端按版本计算
前端和服务端都运行公式引擎。前端随编辑响应,服务端在生成快照或处理文件时,对抓取到的内容版本执行计算。
- 编辑时,浏览器在本地计算受影响的公式,也可以放在 Worker 中执行,计算结果立即显示。协同服务记录这些内容修改并将其同步。
- 生成快照时,服务端的快照策略触发保存流程。服务端先抓取该操作对应的内容版本,使用
univer-rs计算,再将该版本的内容和结果一起保存。 - 重新打开文档时,前端复用快照中仍然有效的结果,应用后续修改并继续计算,避免每次全量重算。
内容修改持续同步;服务端在生成快照时执行计算,结果与对应的内容版本一起保存。
首次加载时,应用根据已保存的结果决定初始计算的方式:
WHEN_EMPTY:复用已保存的公式值,只计算缺失的结果。NO_CALCULATION:初始化时不计算,结果由应用提供。FORCED:已保存的结果需要刷新时,全部重算。
这些选项仅控制首次加载。此后的编辑仍在前端计算;服务端在生成带版本的快照或处理文件时按需计算。配置见公式文档,同步机制见协同总览,文件处理见导入与导出。
公式引擎性能
10 份工作簿的 Univer Rust 公式引擎性能实测涵盖 Rust 输入加载、各阶段耗时、输入格式边界和样张下载。
数组公式的计算与展开
在支持的函数和格式范围内,Rust 遵循 Excel 的数组公式和溢出规则进行计算。计算结果连同锚点和展开范围一并返回,同时支持动态数组和旧式数组公式的声明区域。
例如,在空白的 A1 里写入 =SEQUENCE(3,2),得到的结果是:
| A | B |
|---|---|
| 1 | 2 |
| 3 | 4 |
| 5 | 6 |
公式仍保留在 A1,结果占据 A1:B3。数组缩小时,旧的展开值会被清除;展开区域被占用时返回 #SPILL!。前端展示、Agent 读取和文件导出都可以复用这份计算好的快照。
具体函数和范围规则见公式支持和 Excel 数组展开行为。
接入 Agent 的执行与验证流程
模型、对话和工具编排沿用现有方案。AI SDK 提供一组操作 Office 内容的工具,供该 Agent 调用:
- 检查结构,读取目标内容。
- 在无头运行时中执行 Facade 修改和所需的计算。
- 待计算和提交确认后,读取更新后的状态。
- 核对值和结构;需要视觉验证时,补充截图或布局检查。
内容操作和视觉检查可以配合使用。需要人工审阅时,先将修改放入 Worktree,再进行比较和合并。Univer CLI 演示了如何将这些能力组合成 Agent 可驱动的应用。
如何接入
| 能力 | 可以完成什么 |
|---|---|
| Node.js 内容运行时 | 从 headless Univer 开始,按需启用所需的产品和计算插件。 |
| 后台文件处理 | 将 Rust 计算与 Node.js 文件转换 结合,然后保存或返回更新后的快照。 |
| 共享编辑与 Agent | 接入协同服务和 AI SDK,使人和 Agent 都在已确认的内容上操作。 |
你觉得这篇文档如何?