页面和元素

了解 PDF 页面、原生源内容、可编辑叠加层和坐标系。

文档结构

IPdfDocument 包含规范化的 PDF 文档模型:

  • pages 存储页面顺序、大小、旋转、图层、标签和原生 PDF 边界框。
  • objects 存储语义文档对象。
  • displayLists 保留渲染级 PDF 操作,也保持与源文件的保真度。
  • textStories 保存可编辑的文本流,与不稳定的 PDF 字形分组分开。
  • assets、styles 和 native 保留可复用的资源,以及源文件特有的资源。
  • sources、edits 和 exportPlan 记录内容来源和导出意图。

导入 PDF 时,并非所有可见的源操作都会成为可编辑的 Facade 元素。原生内容会保留在显示列表中,直到用户通过某个操作将其提升或替换。

页面

FPdf 按物化后的顺序读取页面,并可插入空白页:

TypeScript
const pages = pdf.getPages()const firstPage = pdf.getPageByIndex(0)const pageById = firstPage ? pdf.getPageById(firstPage.getId()) : nullconst appendedPage = pdf.insertPage()

insertPage(index) 接受 0 到当前页面数之间的整数。新页面沿用相邻页面的大小、旋转和 PDF 边界框。如果没有相邻页面,则使用 A4 尺寸,即 595 × 842 点。

原生内容与可编辑叠加层

FPdfPage.getElements() 按 z 序返回持久化的可编辑叠加元素,下列带类型的访问器筛选的也是同一叠加层:

访问器Facade 包装器
getTextBoxes()FPdfTextBox
getParagraphs()FPdfParagraph
getLists()FPdfList
getTables()FPdfTable
getImages()FPdfImage
getDividers()FPdfDivider
getAnnotations()FPdfAnnotation

getTextSpans() 的行为不同:它枚举的是可见原生文本操作的快照。对文本片段调用 replaceText() 会抑制对应的原生操作,并新建一个可编辑文本框。

坐标系

核心模型和公共 Facade 使用的单位不同,这是有意设计的:

边界单位与原点
Facade 位置、大小、批注路径和描边宽度PDF 点,以左上角定位
核心模型页面和对象几何EMU,原点在左上角
导入的 pdfBoxes 和原生源映射PDF 用户空间,原点在左下角

应用代码使用 getTransform、setPosition、setSize、setRotation 以及带类型的 Facade 插入选项。只有在构建底层模型数据时,才需要使用 ptToEmu、emuToPt 等相关转换辅助函数。

公共编辑限制

Facade 会校验以下几项模型约束:

  • 宽度和高度必须是有限的正数,位置和旋转必须是有限值。
  • 列表层级范围为 0 到 8,有序列表的起始编号必须是正整数。
  • 表格的宽高必须是正整数,且单元格总数不能超过 10,000。
  • Facade 插入批注时支持高亮、下划线、删除线、波浪线和墨迹批注。
  • 图片不透明度范围为 0 到 1,裁剪矩形必须有正面积。
  • 文本范围使用 UTF-16 偏移量,起点包含、终点不包含。

如需面向任务的示例,请继续阅读编辑 PDF。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.