PDF 单元数据

了解持久化的 IPdfUnitData 契约,以及导入 PDF 内容与持久化编辑之间的边界。

IPdfUnitData

IPdfUnitData 是单个 UNIVER_PDF 单元持久化后的快照。其 schema 为 univer-pdf-unit,当前 schema 版本为 1,修订号从 1 开始。

属性类型用途
schema'univer-pdf-unit'PDF 单元 schema 的稳定标识
schemaVersion1当前 PDF 单元 schema 版本
idstring存储、协作、资源和导出共用的标识
revnumber单元的权威修订号
namestring展示给用户的 PDF 名称
sourceDocumentRefIPdfSourceDocumentRef导入 PDF 工件的不可变来源信息
documentIPdfDocument导入的基线,或空白文档的基线
editStateIPdfDurableEditState已接受并持久化的编辑意图
documentShell?IPdfDocumentShell用于基于块的 PDF 的小型页面目录和分片索引
fragmentIndex?IPdfUnitFragmentIndex从页面和共享数据到已存储分片的逻辑映射
resourceBindings?Record<string, PdfDurableResourceBinding>持久化的原生或 Univer 管理资源绑定
fragmentBindings?Record<string, IPdfFragmentArtifactBinding>独立加载分片的运行时文件绑定
capabilityReport?IPdfCapabilityReport针对支持的操作和回退方案的导入与运行时决策
metadata?Record<string, PdfJsonValue>应用或集成元数据

基线与编辑层

导入的 document 是不可变基线,编辑不会就地重写它。文本替换、插入对象、页面变更、源抑制和托管资源记录在 editState 中,渲染和导出时再投影到基线上。

将两者分开可以保留原生 PDF 内容的来源信息,也让导出器能够决定哪些源操作需要复制、抑制还是替换。

选择正确的视图

pdf.getDocument() 返回导入的基线。pdf.save() 返回包含持久化编辑状态的完整单元快照。高级集成可以通过 pdf.getModel().getMaterializedDocument() 获取当前投影。

创建并持久化快照

TypeScript
const pdf = univerAPI.createPdf({ name: 'Untitled contract' })const page = pdf.getPageByIndex(0)page?.insertTextBox({  text: 'Draft',  left: 36,  top: 36,})const snapshot = pdf.save()await applicationStorage.save(snapshot.id, snapshot)

通过 Facade 恢复完整快照:

TypeScript
const snapshot = await applicationStorage.load('pdf-unit-id')const pdf = univerAPI.createPdf(snapshot)

单元运行后,不要修改快照对象,应改用 Facade 方法或已注册的命令,以确保校验、撤销重做、协作和导出意图保持一致。

基于块的 PDF

大型 PDF 或远程存储的 PDF 可以使用 documentShell、fragmentIndex 和 fragmentBindings。Shell 在加载任何页面正文之前就能提供页面大小、顺序、标签和块 ID。UI 需要时,Provider 会物化页面分片和共享分片。

这些字段是 Exchange 和存储层的契约。应用代码通常从 PDF Exchange 或协作服务获取这些字段,并原样持久化。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.