画在 (72, 72) 的字符串落在页面顶边下方 1 英寸处,这让所有从内容流一侧学 PDF 的人猝不及防——在那个世界里,y = 72 是离底边 1 英寸。第二个意外晚几百行才出现:一份按 US Letter 排版的报告,第一页是 612 × 792 磅,之后的每一页却是 595 × 842,因为设置纸型的那行代码只执行了一次
两个现象同根同源。PDF 里的文本是一小段状态变化(字体和字号、字符间距、单词间距、定位与旋转用的文本矩阵)加一个显示文本操作符,高层文本调用只是这条序列的薄包装。调用会读取这些状态,但绝不会替你重置;新页面从一组固定的默认值开始,而不是从上一页结束时留下的状态开始
TextOut 把 (X, Y) 放在页面的哪里
HotPDF 用 THPDFPage.TextOut(X, Y: Single; angle: Extended; Text: WideString) 画文本,经 Pdf.CurrentPage.TextOut 调用。X 和 Y 从页面左上角量起,Y 向下增长;默认 Resolution 为 72 时一个单位就是一磅,即 1/72 英寸。页面内部把每个 Y 换算成自底向上的 PDF 用户空间——用页高减去它。角度以度为单位;文本是 WideString,Unicode 可以直接穿透。另一个重载接受 PWORD 加长度,服务手里已经有 UTF-16 缓冲的代码
页面几何同样是固定的。BeginDoc 添加第一页,BeginDoc 或 AddPage 创建的每一页都以 A4(595 × 842 磅)起步,当前字体是 Arial 12。US Letter(612 × 792)离你只有一行赋值:CurrentPage.Size := Letter,但这个赋值属于页面,所以每个新页面都得再来一次
默认情况下,你传入的 Y 是文本的顶边,基线在其下方一个字体上升高度处。TextFromBaseLine(True) 把页面切换到基线定位。同一行混排多种字号时应该打开它。顶边模式下,14 磅金额旁边的 9 磅货币代码与金额的顶边对齐,明显浮高;基线模式下两段文本坐在同一条线上,排版师傅就是这么排的。下一个示例的最后一段做的正是这件事
大小和样式都住在 SetFont 里
TextOut 没有字号和样式参数。SetFont(FontName, FontStyle, ASize, FontCharset, IsVertical) 一手包办,后两个参数默认 ANSI_CHARSET 和横排;它设置的一切对之后的每次 TextOut 都有效,直到下一个 SetFont 来替换。大多数第一天的困惑都能追溯到这一点:某行变成了粗体,因为三次调用之前有代码设了 [fsBold],而没有人清掉它
var
W: Single;
begin
Pdf.BeginDoc; // 第一页:A4、Arial 12
Pdf.CurrentPage.TextFromBaseLine(True); // 以下所有 Y 都按基线算
Pdf.CurrentPage.SetFont('Times New Roman', [], 24);
Pdf.CurrentPage.TextOut(72, 72, 0, 'Quarterly Report'); // 24 磅常规
Pdf.CurrentPage.SetFont('Times New Roman', [fsBold], 12);
Pdf.CurrentPage.TextOut(72, 104, 0, 'Revenue'); // 12 磅粗体
Pdf.CurrentPage.SetFont('Times New Roman', [fsItalic], 11);
Pdf.CurrentPage.TextOut(72, 120, 0, 'figures in thousands'); // 11 磅斜体
Pdf.CurrentPage.SetFont('Courier New', [fsBold, fsUnderline], 10);
Pdf.CurrentPage.TextOut(72, 136, 0, '+18.4% YoY'); // 样式可以叠加
// 同一基线上混排字号:趁 14 磅字体还是当前字体时测量
Pdf.CurrentPage.SetFont('Arial', [fsBold], 14);
W := Pdf.CurrentPage.GetWideTextWidth('1,284.50');
Pdf.CurrentPage.TextOut(72, 160, 0, '1,284.50');
Pdf.CurrentPage.SetFont('Arial', [], 9);
Pdf.CurrentPage.TextOut(72 + W + 3, 160, 0, 'EUR'); // 空 3 磅
...
end;
样式参数就是一个普通的 TFontStyles 集合,[] 是常规体,[fsBold, fsItalic] 是粗斜体。fsUnderline 和 fsStrikeOut 画成垫在文本下方或横穿文本的细实心条,文本旋转时它们跟着转。字号以磅为单位,与坐标同单位,垂直方向的算术因此很简单:11 磅正文配 16 磅步进,行与行之间留约 5 磅空隙。没有自动换行前进,每个 Y 都得你自己算——写整段文字时很繁琐,对字段位置固定的表单来说却刚刚好
GetWideTextWidth 用调用那一刻的当前字体测量,所以最后一段的测量必须趁 14 磅粗体还设着的时候做。把它挪到第二个 SetFont 之后,9 磅的后缀就会压在金额的末几位数字上
字体名是拿构建 PDF 的机器上安装的字体来解析的,开发者桌面上能解析到的字体,构建服务器上未必存在,成品文件里的字体取决于产出的那台机器。脚本覆盖是另一半:只覆盖拉丁文的字体被要求画西里尔文或 CJK 时,出来的就是缺字形方框,这是字体文件自身的属性,与调用无关。当一个字符串混排没有任何单一字体全覆盖的脚本时,TextOutWithFallback 接受同样的四个参数,对主字体缺字形的字符逐段切换字体,结束后恢复原字体
角度参数是怎么旋转文本的?
非零角度让文本围绕锚点逆时针转过相应度数,锚点是文本自身坐标系里的左上角。锚点不动,变的只是字形的行进方向,所以放水平标签的坐标同样能放它的旋转孪生。即使页面处于基线模式,旋转文本的锚点仍是这个左上角;TextFromBaseLine 只影响水平文本
var
W, AxisMidY: Single;
begin
AxisMidY := 400; // 图表 Y 轴的中点
// 90 度的文本自下而上阅读,从 Y 起向上生长,
// 所以要在轴上居中,得从中点往下半个宽度处起笔
Pdf.CurrentPage.SetFont('Arial', [fsBold], 11);
W := Pdf.CurrentPage.GetWideTextWidth('Units sold');
Pdf.CurrentPage.TextOut(40, AxisMidY + W / 2, 90, 'Units sold');
// 斜向水印
Pdf.CurrentPage.SetFont('Arial', [fsBold], 60);
Pdf.CurrentPage.TextOut(150, 250, 45, 'DRAFT');
// 倾斜 60 度的列标题:Y 相同,X 递进
Pdf.CurrentPage.SetFont('Arial', [], 9);
Pdf.CurrentPage.TextOut(120, 600, 60, 'Q1 actual');
Pdf.CurrentPage.TextOut(160, 600, 60, 'Q2 actual');
end;
90 度覆盖轴标签和书脊标题。90 度时字形立在锚点 X 的右侧、只有一个行高宽,文本按自身宽度向页面顶部爬升。这就是居中要往 Y 上加半个宽度而不是减的原因,也是锚在轴中点上的标签完全悬在中点上方的原因。60 度适合列标题,让长标签立在窄列上方而不溢入邻列;45 度是常见的水印角度。共享基线的文本拿相同的 Y、让 X 递进,与叠起来的水平行共享 X、让 Y 递进如出一辙
为什么第二页出来是 A4 的 Arial 12?
AddPage 返回新页的索引并把它设为当前页,新页面从默认值出发:A4、Arial 12、顶边定位、字符与单词间距为零。上一页的任何东西都不会带过来。这个设计让每页自成一体——PDF 页面的内容流本来就从全新的图形状态开始——但也意味着任何在文档开头一次性配置页面的排版代码,都会在第二页悄悄换纸型和字体。修法是把每个页面级设置收进一个例程,在 BeginDoc 之后和每次 AddPage 之后都调用它
procedure StartReportPage(Pdf: THotPDF);
begin
Pdf.CurrentPage.Size := Letter; // 新页面默认是 A4
Pdf.CurrentPage.TextFromBaseLine(True); // 新页面默认处于顶边模式
Pdf.CurrentPage.SetFont('Arial', [], 11); // 新页面默认是 Arial 12
end;
procedure WriteReport(Pdf: THotPDF; Lines: TStrings);
const
LeftMargin = 72; // 1 英寸
TopLine = 72; // 第一条基线,向下 1 英寸
BottomMargin = 72;
Leading = 16;
var
I: Integer;
Y: Single;
begin
StartReportPage(Pdf);
Y := TopLine;
for I := 0 to Lines.Count - 1 do
begin
if Y > Pdf.CurrentPage.Height - BottomMargin then // Letter 上是 720
begin
Pdf.AddPage;
StartReportPage(Pdf);
Y := TopLine;
end;
Pdf.CurrentPage.TextOut(LeftMargin, Y, 0, Lines[I]);
Y := Y + Leading;
end;
end;
TextOut 底下没有流式布局,对内容流而言越过页底的 Y 仍是合法坐标:文本写进去了,只是落在媒体框之外,任何查看器都不显示它。所以这个循环在每一行之前检查 Y,自己开新页。把限值从 CurrentPage.Height 读出来而不是硬编码 720,日后有人把辅助例程换回 A4 时循环依然正确——同样的 1 英寸边距在 A4 上限值是 770
最快的检查就是阅读器打印对话框会做的那件事。打开输出,翻到第二页,看文档属性:Letter 页报 8.5 × 11 英寸,A4 页约 8.27 × 11.69。如果第一页和第二页对不上,某个页面级设置就住在辅助例程之外
字符间距和单词间距也是页面状态
有时字符串没问题,宽度不对:要横跨一条固定标尺的标题、数字间松一点更好读的代码、需要拉开间隙的一行标签。ISO 32000-1 为此给了两个文本状态参数:字符间距 Tc(§9.3.2),加在每个字形之后;单词间距 Tw(§9.3.3),加在每个空格处。HotPDF 用 SetCharacterSpacing(Spacing: Single) 和 SetWordSpacing(Spacing: Single) 设置它们,默认分辨率下单位是磅,和字体一样,一旦设置就保持有效直到被改变
单词间距有个写进规范里的坑。§9.3.3 只把 Tw 作用于单字节字符代码 32,明确不作用于多字节编码内部的字节 32,所以对按双字节字形码写出的文本——嵌入 Unicode 字体通常就是这种写法——这个操作符单独用没有任何效果。HotPDF 的 Unicode 文本正是这么写的,在这条路径上它把单词间距落成每个空格字形之后的显式位置调整,所以无论哪种写法 SetWordSpacing 都能拉开间隙。触发条件仍是普通空格 U+0020:不含 ASCII 空格的中文或日文文本一点额外空间都拿不到,表意空格(U+3000)则被当成普通字形对待
标题要达到目标宽度时,字符间距是合适的工具,因为它把改变均匀摊开,而不是堆在空格上。GetWideTextWidth 会把当前生效的字符间距和单词间距算进去,所以测量时两者都要为零,再据此推导间距:
const
Heading = 'SUMMARY';
Target = 200; // 标题要横跨的那条线的宽度,单位磅
var
Natural, Tc: Single;
begin
Pdf.CurrentPage.SetFont('Arial', [fsBold], 14);
Pdf.CurrentPage.SetCharacterSpacing(0); // 测量时不能带残留间距
Natural := Pdf.CurrentPage.GetWideTextWidth(Heading);
// Tc 加在每个字形后面,但可见的只有字形之间的空隙
Tc := (Target - Natural) / (Length(Heading) - 1);
Pdf.CurrentPage.SetCharacterSpacing(Tc); // 负值收紧
Pdf.CurrentPage.TextOut(72, 72, 0, Heading);
Pdf.CurrentPage.SetCharacterSpacing(0); // 正文之前先复位
Pdf.CurrentPage.SetWordSpacing(6);
Pdf.CurrentPage.SetFont('Arial', [], 11);
Pdf.CurrentPage.TextOut(72, 100, 0, 'Name Department Extension');
Pdf.CurrentPage.SetWordSpacing(0);
end;
复位行比设置行更重要。一个标题用了 4 磅字符间距后忘了清零,下面每个段落都继承这份拉伸,读起来是一种说不出的别扭,快速校对发现不了,到印刷稿上才现形。设值,画需要它的那一段,下一行就清零,后面的代码就不必知道前面的章节干了什么。同一个页面还提供 SetHorizontalScaling(Tz,默认 100)用于压缩文本而不改高度,以及 SetTextRenderingMode 配 trStroke 之类的值画描边文本,两者的持久化方式与间距一模一样
如果这是你输出的第一页,HotPDF Hello World 示例讲了文档创建和保存。要让文本填满一整栏,PDF 文本两端对齐有专门的走查,自上而下的 CJK 排版见 HotPDF 中的竖排文本。上面的 TextOut、SetFont、间距调用和纸型设置都随 HotPDF Delphi Component 提供,支持 Delphi 和 C++Builder