文件导入与导出
将 Office 文件转换为对应产品的 Snapshot,并将编辑后的快照导出为文件。
文件导入导出负责连接外部文件格式与 Univer 使用的内容模型。导入把文件解析为对应产品的 Snapshot,导出把产品的 Snapshot 序列化为选定的输出格式。
从文件到快照
Office 文件分为两类。.xlsx、.docx、.pptx 是 OOXML 文件包,包含 XML 和图片等资源;.xls、.doc、.ppt 使用旧版二进制结构。CSV 和 TSV 是纯文本。提交支持格式的原文件后,解码、文件包解析和资源映射均由转换模块完成。
Snapshot 是产品的内容状态,可以保存,也可以恢复。六个产品的数据结构见下文。
导入:文件 → Snapshot
导入将内容、样式和资源解析为对应的产品模型:Sheet、Doc、Slide、Relational Table 等。
导出:Snapshot → 文件
导出读取当前的产品 Snapshot,写出目标格式的结构和资源。Snapshot 是运行时使用的内容模型,通常以 JSON 传输或保存。
以 Sheet 为例,按选定的策略计算公式、透视表和数字格式,然后更新 Snapshot。详见服务端计算。
Snapshot 数据结构
每个产品都定义了自己的 Snapshot 接口,用于持久化内容和资源引用,通常以 JSON 保存。接口链接指向字段定义、类型和示例。
| 产品 | Snapshot 接口 | 主要内容 |
|---|---|---|
| 电子表格(Sheet) | IWorkbookData | 工作表、单元格、共享样式与插件资源。 |
| 文档(Doc) | IDocumentData | 正文、段落、样式、页眉页脚与资源。 |
| 演示文稿(Slide) | ISlideData | 幻灯片、元素、母版、主题与资源。 |
| 关系型表格(Relational Table) | IBaseSnapshot | 表、字段、记录、视图及各自顺序。 |
| 画布(Canvases) | IBoardData | 页面、元素、主题与资源。 |
IPdfUnitData | 源文档、持久化编辑状态与资源绑定。 |
通过产品 Facade 的 save() 获取当前 Snapshot,再使用对应的创建接口恢复。已加载的内容通过 Facade API 修改。PDF 使用 pdf.save(),可同时保留源基线和 editState。
各产品支持的格式
下表中的 Office 与表格格式使用 Rust Exchange 的直接转换入口。PDF 使用独立的转换模块,因此在同一张表中单独列出。
| 产品 | 导入 / 编译 | 导出 | 说明 |
|---|---|---|---|
| 电子表格(Sheet) | .xls, .xlsx, .csv, .tsv | .xlsx, .csv, .tsv | CSV/TSV 对应一个工作表。 |
| 文档(Doc) | .doc, .docx | .docx | 旧版 DOC 导入文档模型,导出为 DOCX。 |
| 演示文稿(Slide) | .ppt, .pptx | .pptx | 旧版 PPT 导入演示文稿模型,导出为 PPTX。 |
| 关系型表格(Relational Table) | .xls, .xlsx, .csv, .tsv | .xlsx, .csv, .tsv | CSV/TSV 对应一个数据表;XLSX 支持表与字段映射。 |
| 画布(Canvases) | Mermaid(.mmd / 源码文本) | .pptx | Mermaid 先生成导入草稿,经 Canvases Facade 应用后再保存 Snapshot;PPTX 导出当前页面。 |
.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 文件转换开始。
格式支持与单项功能的保留是两个不同的问题。请结合各产品的功能清单,使用真实的业务文件检查公式、图片、样式和布局经过导入、编辑、导出后的结果。
你觉得这篇文档如何?