文件导入与导出

将 Office 文件转换为对应产品的 Snapshot,并将编辑后的快照导出为文件。

文件导入导出负责连接外部文件格式与 Univer 使用的内容模型。导入把文件解析为对应产品的 Snapshot,导出把产品的 Snapshot 序列化为选定的输出格式。

从文件到快照

Office 文件分为两类。.xlsx、.docx、.pptx 是 OOXML 文件包,包含 XML 和图片等资源;.xls、.doc、.ppt 使用旧版二进制结构。CSV 和 TSV 是纯文本。提交支持格式的原文件后,解码、文件包解析和资源映射均由转换模块完成。

Snapshot 是产品的内容状态,可以保存,也可以恢复。六个产品的数据结构见下文。

导入:文件 → Snapshot

导入将内容、样式和资源解析为对应的产品模型:Sheet、Doc、Slide、Relational Table 等。

100%

导出:Snapshot → 文件

导出读取当前的产品 Snapshot,写出目标格式的结构和资源。Snapshot 是运行时使用的内容模型,通常以 JSON 传输或保存。

100%

以 Sheet 为例,按选定的策略计算公式、透视表和数字格式,然后更新 Snapshot。详见服务端计算。

Snapshot 数据结构

每个产品都定义了自己的 Snapshot 接口,用于持久化内容和资源引用,通常以 JSON 保存。接口链接指向字段定义、类型和示例。

产品Snapshot 接口主要内容
电子表格(Sheet)IWorkbookData工作表、单元格、共享样式与插件资源。
文档(Doc)IDocumentData正文、段落、样式、页眉页脚与资源。
演示文稿(Slide)ISlideData幻灯片、元素、母版、主题与资源。
关系型表格(Relational Table)IBaseSnapshot表、字段、记录、视图及各自顺序。
画布(Canvases)IBoardData页面、元素、主题与资源。
PDFIPdfUnitData源文档、持久化编辑状态与资源绑定。

通过产品 Facade 的 save() 获取当前 Snapshot,再使用对应的创建接口恢复。已加载的内容通过 Facade API 修改。PDF 使用 pdf.save(),可同时保留源基线和 editState。

各产品支持的格式

下表中的 Office 与表格格式使用 Rust Exchange 的直接转换入口。PDF 使用独立的转换模块,因此在同一张表中单独列出。

产品导入 / 编译导出说明
电子表格(Sheet).xls, .xlsx, .csv, .tsv.xlsx, .csv, .tsvCSV/TSV 对应一个工作表。
文档(Doc).doc, .docx.docx旧版 DOC 导入文档模型,导出为 DOCX。
演示文稿(Slide).ppt, .pptx.pptx旧版 PPT 导入演示文稿模型,导出为 PPTX。
关系型表格(Relational Table).xls, .xlsx, .csv, .tsv.xlsx, .csv, .tsvCSV/TSV 对应一个数据表;XLSX 支持表与字段映射。
画布(Canvases)Mermaid(.mmd / 源码文本).pptxMermaid 先生成导入草稿,经 Canvases Facade 应用后再保存 Snapshot;PPTX 导出当前页面。
PDF.pdf.pdf需要 PDF 转换服务,与 Rust Exchange CLI 的转换入口分开。
  • .xls、.doc、.ppt 是导入格式,导出格式分别为 .xlsx、.docx、.pptx。
  • CSV/TSV 每次导出一个工作表或一个 Relational Table 数据表。需要保留完整的内容模型及其资源时,保存对应的产品 Snapshot。
  • 不同 SDK 入口接受的扩展名不同。.xlsm、.pptm、.ppsx、.ppsm、.potx 等格式需要确认所部署的后端和浏览器 API,它们不是 Rust CLI 额外支持的直接格式名。

转换过程中的计算

在支持的电子表格转换链路中,文件转换可以与服务端计算组合使用:

  • 公式计算在导入时补齐缺失的缓存结果,或在导出前按选定的策略重新计算。
  • 透视表计算根据源数据和透视配置得出分组与聚合结果,再将其写入 Snapshot 或导出的工作簿。
  • 数字格式计算根据数值和格式码生成日期、百分比、货币等显示文本。CSV/TSV 导出可以选择写入显示值或原始值。

相关的内容处理流程见无头与服务端计算。

接入方式

文件转换属于 Server SDK。上传、任务处理、存储和下载接口由应用提供。Snapshot 转换可以不依赖协同运行。导出共享文档则不同:需等待改动同步完成,再读取已确认的版本。

可以从导入导出集成和 Node.js 文件转换开始。

格式支持与单项功能的保留是两个不同的问题。请结合各产品的功能清单,使用真实的业务文件检查公式、图片、样式和布局经过导入、编辑、导出后的结果。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.