无头与服务端计算

在 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 计算,再将该版本的内容和结果一起保存。
  • 重新打开文档时,前端复用快照中仍然有效的结果,应用后续修改并继续计算,避免每次全量重算。
100%

内容修改持续同步;服务端在生成快照时执行计算,结果与对应的内容版本一起保存。

首次加载时,应用根据已保存的结果决定初始计算的方式:

  • WHEN_EMPTY:复用已保存的公式值,只计算缺失的结果。
  • NO_CALCULATION:初始化时不计算,结果由应用提供。
  • FORCED:已保存的结果需要刷新时,全部重算。

这些选项仅控制首次加载。此后的编辑仍在前端计算;服务端在生成带版本的快照或处理文件时按需计算。配置见公式文档,同步机制见协同总览,文件处理见导入与导出。

公式引擎性能

10 份工作簿的 Univer Rust 公式引擎性能实测涵盖 Rust 输入加载、各阶段耗时、输入格式边界和样张下载。

数组公式的计算与展开

在支持的函数和格式范围内,Rust 遵循 Excel 的数组公式和溢出规则进行计算。计算结果连同锚点和展开范围一并返回,同时支持动态数组和旧式数组公式的声明区域。

例如,在空白的 A1 里写入 =SEQUENCE(3,2),得到的结果是:

AB
12
34
56

公式仍保留在 A1,结果占据 A1:B3。数组缩小时,旧的展开值会被清除;展开区域被占用时返回 #SPILL!。前端展示、Agent 读取和文件导出都可以复用这份计算好的快照。

具体函数和范围规则见公式支持和 Excel 数组展开行为。

接入 Agent 的执行与验证流程

模型、对话和工具编排沿用现有方案。AI SDK 提供一组操作 Office 内容的工具,供该 Agent 调用:

  1. 检查结构,读取目标内容。
  2. 在无头运行时中执行 Facade 修改和所需的计算。
  3. 待计算和提交确认后,读取更新后的状态。
  4. 核对值和结构;需要视觉验证时,补充截图或布局检查。

内容操作和视觉检查可以配合使用。需要人工审阅时,先将修改放入 Worktree,再进行比较和合并。Univer CLI 演示了如何将这些能力组合成 Agent 可驱动的应用。

如何接入

能力可以完成什么
Node.js 内容运行时从 headless Univer 开始,按需启用所需的产品和计算插件。
后台文件处理将 Rust 计算与 Node.js 文件转换 结合,然后保存或返回更新后的快照。
共享编辑与 Agent接入协同服务和 AI SDK,使人和 Agent 都在已确认的内容上操作。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.