技术文章

Delphi HotPDF Hello World:你的第一个 PDF 程序

Delphi 里的 HotPDF Hello World 是一个控制台程序,全部围绕一个 THotPDF 对象的四次调用展开:设置文档属性,调用 BeginDoc,用 SetFont 和 TextOut 绘制,最后调用 EndDoc。下面的程序原样就能编译,会写出一页 A4 PDF,用十一种语言向读者问好。篇幅虽短,这第一页已经碰到了新手生成 PDF 时最容易搞错的三件事:坐标从哪个角数起,每种文字的字形实际存在哪个字体里,以及新页面是从什么状态出发的

Delphi 里 HotPDF Hello World 四步程序流程示意图,标出左上角页面原点与两个设置陷阱
配置、开始、绘制、结束,整个程序就这四步,Y 值从左上角向下数

完整的 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.
HotPDF Delphi 组件生成的多语言 Hello World PDF,144 dpi 渲染:拉丁、西里尔、日文、中文和韩文共十一种问候语
生成的 A4 页面顶部,第一行从距上、左边缘各一英寸处起画

跑一下,工作目录里就会出现 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 之上的一个块里,这两条消息你一条也碰不上

有三个默认值值得在每个程序里想清楚再定,第一个程序也不例外:

属性默认值生成正式输出时原因
CompressioncmNonecmFlateDecode不加过滤器时,内容流按纯文本存放;Flate 就是 ISO 32000-1 §7.4.4 里的 deflate 过滤器
AutoLaunchTrueFalseEndDoc 一返回,成品 PDF 就会用关联查看器打开,在服务或构建任务里这是不对的
EnableFontSubsettingFalseTrue只嵌入实际画到的字形,而不是完整字体文件

未压缩的流也并非没用。在你摸索 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,从矢量图形、图像到表单和数字签名