技术文章

Delphi 中的 HotPDF TextOut:大小、样式、旋转和间距

画在 (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 接受同样的四个参数,对主字体缺字形的字符逐段切换字体,结束后恢复原字体

HotPDF TextOut 页面:Arial、Times New Roman 和 Courier New 在多个字符集下以常规、粗体和斜体样式渲染

角度参数是怎么旋转文本的?

非零角度让文本围绕锚点逆时针转过相应度数,锚点是文本自身坐标系里的左上角。锚点不动,变的只是字形的行进方向,所以放水平标签的坐标同样能放它的旋转孪生。即使页面处于基线模式,旋转文本的锚点仍是这个左上角;TextFromBaseLine 只影响水平文本

HotPDF TextOut 旋转几何示意图:0、45、90 度的文本围绕固定锚点逆时针旋转,并附书脊标签、水印和倾斜列标题的 Delphi TextOut 调用示例
非零角度让文本围绕不动的锚点——文本自身的左上角——逆时针旋转,共享基线的文本沿 X 步进,与水平行沿 Y 步进的方式完全一致
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 之后都调用它

HotPDF:US Letter 页面示意图,左侧是行位置算术——左边距、顶部起始线、固定 Leading 一步步走向下边距限值,旁边是带手工 AddPage 守卫和 SetFont 复位的具名常量排版循环
具名锚点把一列魔法数字变成算术:每行把运行中的 Y 加上 Leading,并用 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) 设置它们,默认分辨率下单位是磅,和字体一样,一旦设置就保持有效直到被改变

HotPDF:字符间距 Tc 把额外空间均匀摊到 SUMMARY 的每个字形之后,单词间距 Tw 则只在空格字符处集中投放,两者都接在设置、绘制、复位的循环里,防止间距状态泄漏进后面的段落
Tc 把调整摊到每个字形上,Tw 只作用于空格字符,下一行就复位能让绘制状态保持干净

单词间距有个写进规范里的坑。§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 TextOut 页面:水平缩放、字符间距、单词间距与填充和描边渲染模式的对比

如果这是你输出的第一页,HotPDF Hello World 示例讲了文档创建和保存。要让文本填满一整栏,PDF 文本两端对齐有专门的走查,自上而下的 CJK 排版见 HotPDF 中的竖排文本。上面的 TextOut、SetFont、间距调用和纸型设置都随 HotPDF Delphi Component 提供,支持 Delphi 和 C++Builder