PDF 单元数据
了解持久化的 IPdfUnitData 契约,以及导入 PDF 内容与持久化编辑之间的边界。
IPdfUnitData
IPdfUnitData 是单个 UNIVER_PDF 单元持久化后的快照。其 schema 为 univer-pdf-unit,当前 schema 版本为 1,修订号从 1 开始。
| 属性 | 类型 | 用途 |
|---|---|---|
schema | 'univer-pdf-unit' | PDF 单元 schema 的稳定标识 |
schemaVersion | 1 | 当前 PDF 单元 schema 版本 |
id | string | 存储、协作、资源和导出共用的标识 |
rev | number | 单元的权威修订号 |
name | string | 展示给用户的 PDF 名称 |
sourceDocumentRef | IPdfSourceDocumentRef | 导入 PDF 工件的不可变来源信息 |
document | IPdfDocument | 导入的基线,或空白文档的基线 |
editState | IPdfDurableEditState | 已接受并持久化的编辑意图 |
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 或协作服务获取这些字段,并原样持久化。
你觉得这篇文档如何?