Delphi 里的 HotPDF Hello World 是一个控制台程序,全部围绕一个 THotPDF 对象的四次调用展开:设置文档属性,调用 BeginDoc,用 SetFont 和 TextOut 绘制,最后调用 EndDoc。下面的程序原样就能编译,会写出一页 A4 PDF,用十一种语言向读者问好。篇幅虽短,这第一页已经碰到了新手生成 PDF 时最容易搞错的三件事:坐标从哪个角数起,每种文字的字形实际存在哪个字体里,以及新页面是从什么状态出发的
完整的 Hello World 程序
program HelloWorld;
{$APPTYPE CONSOLE}
uses
Winapi.Windows, // DEFAULT_CHARSET;Delphi 7 到 XE 用普通 Windows 单元
HPDFDoc; // HotPDF 主单元
const
LatinFont = 'Arial'; // 拉丁、西里尔和土耳其文
JapaneseFont = 'Yu Gothic';
ChineseFont = 'Microsoft YaHei';
KoreanFont = 'Malgun Gothic';
// 一行文字:先选字体,再绘制。Y 从顶部起量
procedure WriteLine(Pdf: THotPDF; Y: Single; const FontName: AnsiString;
const Text: string);
begin
Pdf.CurrentPage.SetFont(FontName, [], 14, DEFAULT_CHARSET);
Pdf.CurrentPage.TextOut(72, Y, 0, Text);
end;
procedure CreateHelloWorld(const FileName: string);
var
Pdf: THotPDF;
begin
Pdf := THotPDF.Create(nil);
try
// 1. 文档级设置,全部放在 BeginDoc 之前
Pdf.FileName := FileName;
Pdf.AutoLaunch := False; // 默认 True,EndDoc 后会打开查看器
Pdf.Compression := cmFlateDecode; // 默认 cmNone,内容流按纯文本存放
Pdf.FontEmbedding := True; // 本就是默认值,写出来图个明白
Pdf.EnableFontSubsetting := True; // 只嵌入实际画到的字形
// 2. 启动文档,同时创建第 1 页(A4)
Pdf.BeginDoc;
// 3. 绘制:每种文字一个字体,行距 30 点
WriteLine(Pdf, 72, LatinFont, 'Hello, Delphi PDF world!');
WriteLine(Pdf, 102, LatinFont, 'Hola, mundo Delphi PDF!');
WriteLine(Pdf, 132, LatinFont, 'Hallo, Delphi PDF Welt!');
WriteLine(Pdf, 162, LatinFont, 'Bonjour, monde PDF Delphi !');
WriteLine(Pdf, 192, LatinFont, 'Ciao, mondo Delphi PDF!');
WriteLine(Pdf, 222, LatinFont, 'Olá, mundo Delphi PDF!');
WriteLine(Pdf, 252, LatinFont, 'Привет, мир Delphi PDF!');
WriteLine(Pdf, 282, LatinFont, 'Merhaba, Delphi PDF dünyası!');
WriteLine(Pdf, 312, JapaneseFont, 'こんにちは、Delphi PDFの世界!');
WriteLine(Pdf, 342, ChineseFont, '你好,Delphi PDF世界!');
WriteLine(Pdf, 372, KoreanFont, '안녕하세요, Delphi PDF 세계!');
// 4. 写出文件
Pdf.EndDoc;
finally
Pdf.Free;
end;
end;
begin
CreateHelloWorld('HelloWorld.pdf');
Writeln('Wrote HelloWorld.pdf');
end.

跑一下,工作目录里就会出现 HelloWorld.pdf。THotPDF.Create(nil) 配 try ... finally Free 是 Delphi 惯常的所有权模式,生成 PDF 也改变不了这一点。编译上还有一个比什么都重要的细节:源码里有西里尔和 CJK 字符串字面量,要存成带 BOM 的 UTF-8,Delphi IDE 对新建文件就是这么做的。命令行编译器会把不带 BOM 的源文件按系统 ANSI 代码页读入,这些字面量还没到 HotPDF 手里就已经被读坏了。如果你的构建流程生成的源码不带 BOM,就给 dcc32 传 --codepage:65001
在查看器的文档属性里打开字体列表,或者跑一下 pdffonts HelloWorld.pdf,你会看到四个嵌入字体,名字形如 WDDGWW+ArialMT 和 FHYING+YuGothic-Regular。那六个大写字母加一个加号就是子集标签,ISO 32000-1 §9.6.4 规定只含部分字形的字体要用它。看到这个标签,就说明子集化确实发生了——这是最快的验证办法
文档属性为什么必须放在 BeginDoc 之前?
BeginDoc 一执行就把文档敲定了:它要构建 catalog 和页面树并创建第一页,所以凡是影响整个文件的事都必须在它运行之前定下来。HotPDF 是强制执行这一点,而不是留给惯例。在 BeginDoc 之后给 Compression 赋值,setter 会抛出消息为 Cannot set Compression value - document in progress. 的异常;AutoLaunch 也有同样的守卫。把所有文档级设置集中放在 BeginDoc 之上的一个块里,这两条消息你一条也碰不上
有三个默认值值得在每个程序里想清楚再定,第一个程序也不例外:
| 属性 | 默认值 | 生成正式输出时 | 原因 |
|---|---|---|---|
Compression | cmNone | cmFlateDecode | 不加过滤器时,内容流按纯文本存放;Flate 就是 ISO 32000-1 §7.4.4 里的 deflate 过滤器 |
AutoLaunch | True | False | EndDoc 一返回,成品 PDF 就会用关联查看器打开,在服务或构建任务里这是不对的 |
EnableFontSubsetting | False | True | 只嵌入实际画到的字形,而不是完整字体文件 |
未压缩的流也并非没用。在你摸索 HotPDF 都写了哪些操作符的阶段,一个能用文本编辑器直接打开的文件就是好老师,想看内部结构时不妨临时把 Flate 关掉。但凡是要交付的东西,一律压缩。如果测试或 CI 运行不允许弹出查看器,而你又改不了代码,把环境变量 HOTPDF_SUPPRESS_AUTO_LAUNCH 设成 1(true、yes、on 也行),这个进程就会忽略 AutoLaunch
子集化对 CJK 最要紧。Microsoft YaHei、Yu Gothic 和 Malgun Gothic 各自带几千个字形,整个嵌入的话,一页问候语就能凭空多出好几 MB。FontEmbedding 默认就是 True,字体随文件走,在从没装过这些字体的机器上也能正常渲染。只有当下游有人要编辑文本或填写表单域、需要你没画到的字形时,才把子集化关掉
HotPDF 页面上 (0, 0) 在哪里?
HotPDF 的页面坐标从左上角起量,Y 向下增长,和 VCL TCanvas 用的是同一套坐标系。默认 Resolution 为 72 时,一个单位就是一个 PostScript 点,即 1/72 英寸。底下的 PDF 文件仍按规范自己的坐标系来:ISO 32000-1 §8.3.2.3 把默认用户空间的原点放在左下角,Y 向上增长。HotPDF 写内容流时把你传入的每个 Y 用页高去减,把两套坐标接了起来
这笔算术值得亲手算一遍。BeginDoc 和 AddPage 创建的 A4 页面是 595 × 842 点。离顶边一英寸的行,在 HotPDF 里是 Y = 72,在原始 PDF 坐标里是 y = 770,因为 842 − 72 = 770。移植时最经典的错误,就是把规范示例或自底向上库代码里的 770 直接抄过来:TextOut 会把文字放到顶边往下 770 点、离底边只剩一英寸的位置,页面其余部分全空着
第二个细节是 Y 到底指文字的哪个部位。在 PDF 里,Td 和 Tm 操作符设定的文字位置是基线上的字形原点。HotPDF 的默认行为却跟着 GDI 走:Y 是行的顶边,HotPDF 先往下移一个文本高度,再放基线。从 GDI 移植来的代码正好就是这么预期的。从别的 PDF 库移植来的代码通常预期的是基线,于是每一行都比计划低出一个文本高度。THPDFPage.TextFromBaseLine(True) 把当前页切到基线定位:
// 为本文写的辅助函数,不是 HotPDF 的一部分。
// 默认 Resolution 72 下有效
function FromBottomUp(Page: THPDFPage; PdfY: Single): Single;
begin
Result := Page.Height - PdfY;
end;
procedure DrawFromPdfCoordinates(Pdf: THotPDF);
begin
Pdf.CurrentPage.SetFont('Arial', [], 12);
// 从这里起,Y 指的是基线,正如 PDF 自家文本操作符的做法
Pdf.CurrentPage.TextFromBaseLine(True);
// 基线在底边上方 770 点,即顶边下方 72 点
Pdf.CurrentPage.TextOut(72, FromBottomUp(Pdf.CurrentPage, 770), 0,
'Baseline one inch below the top edge');
end;
有两个设置会改变这些数字的含义,每个程序选定一种约定就好,别混着用。把 THotPDF.Resolution 设为 96,X、Y、边距和 TextWidth 的结果都以 1/96 英寸表示,版式按屏幕像素设计时很顺手;页面 Width 和 Height 报告的仍是点数,需要按绘图单位表示的页面尺寸时,读 CurrentPage.UserWidth 和 CurrentPage.UserHeight。MeasurementUnit(默认 muPoints,另有 muMM、muCentimeters、muInches、muTwips 和 muPixels)是更干净的开关,如果你更愿意按毫米思考
为什么每种文字各配一个字体?
因为 PDF 查看器只能画出嵌入字体程序里实际有的字形,而 Windows 自带的字体没有一个能同时覆盖拉丁、西里尔、日文、中文和韩文。前八行交给 Arial,包括西里尔问候语和土耳其语里那个无点的 ı。Yu Gothic、Microsoft YaHei 和 Malgun Gothic 分别是 Windows 上日文、简体中文和韩文的标准字体。老示例常常一律用 Arial Unicode MS,但那个字体是随 Microsoft Office 而不是随 Windows 走的,一台干净的构建服务器上它压根就不在
覆盖面还不是唯一的理由。日文和中文的大多数汉字在 Unicode 里靠 Han unification 共用码位,可两种书写传统对其中不少字的写法并不一样。用中文字体渲染日文,出来的是中式的字形写法,日本读者一眼就能看出来。按语言选字体,而不只看字形存不存在,页面在读者眼里才像样
SetFont 的第四个参数是 Windows 字符集,默认 ANSI_CHARSET,它向 GDI 要的是该字体的西文代码页版本。传 DEFAULT_CHARSET(值 1)则让 Windows 只按名称匹配字体,多语言页面要的正是这个。在文件内部,HotPDF 把每个字体写成 Type 0 复合字体,配 CIDFontType2 子字体、Identity-H 编码和一个 ToUnicode CMap,这些结构见 ISO 32000-1 §9.7 和 §9.10。正是靠 CMap,这些问候语被选中后复制出来的还是文字,而不是一串字形 ID
HotPDF 嵌入的是 Windows 把名称解析到的那个字体。请求的字体缺席时,Windows 二话不说换一个顶上,替补覆盖不到的文字就显示成空框,也就是该字体的 .notdef 字形。新机器产出的第一个文件,先查一遍它的字体列表,再放心交给批量任务。当一个字体装不下整个字符串时,TextOutWithFallback 接受与 TextOut 相同的参数,为每个字符解析字体,每一段都用带这些字形的字体绘制,之后恢复你的原字体。阿拉伯语和希伯来语除了字形覆盖,还需要整形和从右向左的排序,那是RtLTextOut 函数的职责
第二页为什么用 12 号 Arial 打印?
因为每个新页都从一个已知状态出发。THotPDF.AddPage 把新页设为当前页、定成 A4,并调用 SetFont('Arial', [], 12),无论 Resolution 是多少都保持 12 点。BeginDoc 创建第一页走的也是同一条路径,这正是字体在 BeginDoc 之后而不是之前选定的原因。你在第一页调用的 SetFont 不会带到第二页。第二页上的拉丁文看着仍然正常,只是小了些;CJK 文字则变成 .notdef 空框,因为 Arial 没有它们的字形
Hello World 不受影响,因为 WriteLine 每一行都重新设字体。多数真实程序是每页设一次,对它们来说,可预期的起始状态才是正确的设计:第五页的绘制代码永远不必操心第四页碰巧留下了什么。代价是每页设置得重复,而重复得最干净的办法,是让每一页——包括第一页——都过同一个过程:
// 你自己的辅助函数:新页需要的一切都在一处
procedure SetUpPage(Pdf: THotPDF);
begin
Pdf.CurrentPage.SetFont('Arial', [], 14, DEFAULT_CHARSET);
// TextFromBaseLine、颜色和其他每页设置也放这里
end;
procedure WriteRows(Pdf: THotPDF; const Rows: array of string);
const
TopMargin = 72;
Leading = 30;
RowsPerPage = 24;
var
I, Row: Integer;
begin
SetUpPage(Pdf); // 第 1 页已由 BeginDoc 创建
Row := 0;
for I := 0 to High(Rows) do
begin
if Row = RowsPerPage then
begin
Pdf.AddPage; // 这里会被重置回 Arial 12
SetUpPage(Pdf);
Row := 0;
end;
Pdf.CurrentPage.TextOut(72, TopMargin + Row * Leading, 0, Rows[I]);
Inc(Row);
end;
end;
24 行、行距 30 点,最后一行从 Y = 762 起画,A4 底边大约还剩一英寸边距。新需求来了——比如换个字号,或者加个带颜色的标题——只需在 SetUpPage 里改一次,就能到达每一页
画完第一页,接下来去哪
接下来的方向是文字的字号、样式与旋转,以及在一页上有章法地摆放多个块,TextOut 示例会带你逐个过一遍。线条、矩形和图像用同一个 CurrentPage 对象、同一套左上角坐标,所以上文关于原点和每页设置的一切对它们原样适用。HotPDF Delphi Component 产品页覆盖 Delphi 和 C++Builder 的其余 API,从矢量图形、图像到表单和数字签名