【BuildFlow 筑流】PDF 文档结构与图形基础

PDF 简介

PDF（Portable Document Format，可移植文档格式）是全球领先的打印页面描述语言。最初由 Adobe 公司开发并作为专有格式，于 2008 年正式成为开放标准。经过多年发展，PDF 标准已演进至 2.0 版本。由于 PDF 具备完整的向后兼容性和良好的向前兼容性，本文将聚焦于通用的 PDF 标准和规范，而非特定版本。

学习 PDF 文件结构的目的

在 BuildFlow 项目中，我们需要输出 PDF 格式的文档。深入了解 PDF 文件结构对于：

• 准确生成符合标准的 PDF 文档
• 优化文档生成性能和文件大小
• 实现复杂的版面布局和图形效果
• 确保跨平台显示的一致性
• 调试和修复 PDF 生成过程中的问题

具有至关重要的意义。

PDF 文档物理结构

PDF 文件由四个核心部分组成：

• 文件头：标识文件为 PDF 格式并声明版本号

%PDF-1.0    % PDF 版本 1.0 的文件头标识

• 文件体：文档的主要内容区域，由一系列对象构成，定义页面结构、内容元素及相关资源

• 交叉引用表：记录各对象在文件中的偏移地址，支持随机访问，提升解析效率

• 文件尾：标记交叉引用表位置，并以特定标识结束文档

%%EOF

PDF 文档逻辑结构

标准 PDF 文档必须包含以下核心对象：

• 根节点对象：文档的根节点，类似于 XML 的根元素
• 页面树对象：包含文档的页面结构信息
• 页面对象：描述单个页面的属性和内容
• 页面内容对象：定义页面中显示的具体内容（通常为字节流）
• 页面资源对象：提供内容对象引用的资源（字体、画笔、画刷等）
• Trailer 字典：作为文档入口点，包含根节点位置、交叉引用表大小等关键信息

对象间的引用关系如下：

Trailer Dictionary → Root → Page Tree ↔ Page → Resources、Page Content

实战：创建 PDF “Hello World” 文档

基础结构搭建

首先创建文本文件并保存为 PDF 格式，定义文件头：

%PDF-1.4    % 声明 PDF 版本为 1.4

对象定义

1. 页面树对象

1 0 obj
<< /Type /Pages/Count 1           % 单页文档/Kids [2 0 R]      % 引用页面对象（对象2）
>>
endobj

1 0 obj 定义编号为 1 的对象，类型为页面树（Pages），包含一个页面对象引用。

2. 页面对象

2 0 obj
<< /Type /Page/MediaBox [0 0 612 792]    % 美国信纸尺寸（612×792 磅）/Resources 3 0 R           % 引用资源对象/Contents [4 0 R]          % 引用内容对象
>>
endobj

采用磅作为单位确保设备无关的显示效果。

3. 资源对象

3 0 obj
<< /Font<< /F0<< /Type /Font/BaseFont /Times-Italic/Subtype /Type1 >>>>
>>
endobj

定义 Times-Italic 字体资源，标识为 F0。

4. 页面内容对象

4 0 obj
<< >>
stream
1. 0. 0. 1. 50. 700. cm    % 坐标变换：平移至 (50,700)
BT                          % 开始文本块
/F0 36 Tf                   % 使用 36pt 的 F0 字体
(Hello, World!) Tj          % 显示文本
ET                          % 结束文本块
endstream
endobj

通过图形流定义文本显示位置和内容。

5. 根节点对象

5 0 obj
<< /Type /Catalog/Pages 1 0 R             % 引用页面树对象
>>
endobj

6. 交叉引用表与文件尾

xref
0 6
0000000000 65535 f
0000000015 00000 n
0000000074 00000 n
0000000168 00000 n
0000000267 00000 n
0000000523 00000 ntrailer
<< /Size 6/Root 5 0 R >>
startxref
573
%%EOF

PDF 文档解析流程

1. 文件识别：解析器通过文件头识别 PDF 格式及版本
2. 定位文件尾：查找 %%EOF 标记，逆向定位 startxref 获取交叉引用表偏移
3. 读取 Trailer：获取文档根节点等关键信息
4. 构建对象图：通过交叉引用表快速定位并解析所需对象
5. 渲染内容：根据页面对象、资源对象和内容对象渲染最终页面

PDF 对象系统

基本对象类型

• 数值：整数（43）、实数（12.2）
• 字符串：括号包裹（(Hello World)），支持编码指定
• 名称：斜杠开头（/Page），用作字典键
• 布尔值：true / false
• 空对象：null

复合对象类型

• 数组：有序对象集合，如 [0 0 0 1] 或 [2 0 R]
• 字典：键值对集合，如 <</Kids [2 0 R]>>
• 流：包含二进制数据和属性字典，用于页面内容存储

间接引用

通过对象编号和世代号建立对象间链接：

1 0 obj
<< /Kids [2 0 R] >>  % 引用对象2
endobj

R 表示引用（Reference），支持文档的模块化结构。

流对象

语法结构：

4 0 obj
<< /Length 202 >>    % 流数据长度
stream
% 二进制数据
endstream
endobj

PDF 图形坐标系与变换

坐标系基础

PDF 使用与数学相同的笛卡尔坐标系：

• X 轴：水平向右递增
• Y 轴：垂直向上递增
• 单位：磅（1 磅 = 1/72 英寸），确保设备无关性

二维图形变换

1. 平移变换

1 0 0 1 50 700 cm    % 平移至 (50,700)

对应变换矩阵：

[ 1  0  0 ]
[ 0  1  0 ]
[ 50 700 1 ]

2. 旋转变换
绕点 (C_x, C_y) 旋转 θ 角度的复合矩阵：

[ cosθ  sinθ  0 ]
[ -sinθ cosθ  0 ]
[ C_x(1-cosθ)+C_ysinθ  C_y(1-cosθ)-C_xsinθ  1 ]

3. 缩放变换

[ s_x  0   0 ]
[ 0   s_y  0 ]
[ 0    0   1 ]

图形状态管理

使用 q/Q 操作符管理图形状态栈：

stream
200 200 100 100 re S    % 原始矩形
q                       % 保存当前状态
0.7 0.7 -0.7 0.7 200 -80 cm    % 应用变换
200 200 100 100 re S    % 变换后矩形
Q                       % 恢复之前状态
400 400 100 100 re S    % 使用原始坐标系
endstream

PDF 图形操作符详解

图形操作符分类

1. 图形状态操作符：管理 CTM、颜色、裁剪路径等
2. 路径构造操作符：定义直线、曲线、矩形等几何路径
3. 路径绘制操作符：执行描边、填充、裁剪操作
4. 其他绘图操作符：处理图像、渐变等
5. 文本操作符：控制字体选择、字符显示
6. 标记内容操作符：支持图层等功能

路径构造操作符

操作符	功能说明
m	移动画笔到指定位置 (moveto)
l	从当前位置画直线到指定点 (lineto)
re	构造矩形路径
c	构造三次贝塞尔曲线
h	闭合路径（连接起点与终点）

示例：直线绘制

400 400 m 100 100 l S    % 从 (400,400) 到 (100,100) 的直线

示例：矩形路径

100 100 200 200 re       % 起点 (100,100)，尺寸 200×200

示例：贝塞尔曲线

100 100 m 200 300 300 400 400 200 c S

需要起始点、两个控制点和结束点共同定义曲线形状。

路径绘制操作符

操作符	功能说明
S	描边路径 (stroke)
s	闭合并描边路径
f	非零缠绕规则填充
f*	奇偶规则填充
B	填充并描边（非零规则）
B*	填充并描边（奇偶规则）

填充规则详解

非零缠绕规则

• 从点向外引射线，顺时针交叉+1，逆时针交叉-1
• 最终结果非零则填充

奇偶规则

• 计算射线与路径的交点数量
• 奇数个交点则填充

100 350 200 200 re
120 370 160 160 re f     % 非零规则填充400 350 200 200 re  
420 370 160 160 re f*    % 奇偶规则填充

裁剪区域定义

使用 W（非零规则）或 W*（奇偶规则）定义裁剪区域：

100 100 200 200 re h
W                         % 设置矩形为裁剪区域
150 150 m 200 200 l S     % 在区域内，正常显示
0 0 m 500 800 l S         % 仅显示区域内部分

图形状态参数

PDF 维护的图形状态包含以下关键参数：

参数	类型	初始值	说明
CTM	array	单位矩阵	当前变换矩阵
clipping path	internal	CropBox	当前裁剪路径
color space	name/array	DeviceGray	颜色空间
color	various	black	当前颜色
line width	number	1.0	线宽
line cap	integer	0	线端样式
line join	integer	0	线连接样式
dash pattern	array	[] 0	虚线模式
alpha constant	number	1.0	透明度

总结

PDF 通过精确定义的对象系统和图形模型，实现了跨平台的文档一致性。对于 BuildFlow 项目的 PDF 输出功能，掌握以下核心要点至关重要：

1. 结构化存储：通过对象引用构建文档层次结构
2. 设备无关性：使用磅作为基本单位，确保显示一致性
3. 高效解析：交叉引用表支持随机访问
4. 强大图形：完整的2D图形变换和路径模型
5. 状态管理：图形状态栈支持复杂的绘图操作

理解这些基础概念为在 BuildFlow 项目中实现高质量 PDF 输出功能奠定了坚实基础，也为后续掌握 PDF 高级特性（如透明度、图层、交互表单等）提供了必要准备。