技术文章

在 Delphi 中使用 losLab PDF 库将 RTF 转换为 PDF

RTF 存在得够久,久到会出现在没人计划过的地方:遗留报表生成器、邮件合并管道、早于现代文字处理器的法律文档档案。把它即时转成 PDF 是一项反复出现的需求,而在 Windows 上真正行得通的路子不是专用 RTF 解析器,而是 Windows 自己经 TRichEdit 和 EM_FORMATRANGE 提供的渲染路径。losLab PDF Library 暴露一个虚拟设备上下文,正好插进这条管道

机制:虚拟 DC 和 EM_FORMATRANGE

Rich Edit 控件可以针对任何设备上下文给内容分页,不限于物理打印机。EM_FORMATRANGE 消息让控件把一段字符排版进给定的 DC,并返回它装下的最后一个字符的位置。反复调用、每次推进 cpMin,就得到逐页输出。losLab PDF Library 的 GetCanvasDC 提供一个按你指定页面尺寸设定的内存 DC;把一页渲染进去之后,LoadFromCanvasDC 把结果捕获为一份新的单页 PDF 文档。整条管道就这些

有件事要提前做对:TRichEdit 控件的尺寸必须与目标页面匹配。控件比 DC 尺寸小了或大了,分页都跟 PDF 里的成不了行。A4 输出的标准做法:在加载 RTF 文件之前,用与给 DC 定尺寸相同的毫米换像素换算,把控件的像素尺寸调成 210 x 297 mm 在稍后传给 LoadFromCanvasDC 的同一个 DPI 下的样子

PDF:RTF 到 PDF 管道:尺寸设定的 Rich Edit 控件经 EM_FORMATRANGE 把文本分页到虚拟画布 DC,每轮捕获为一页 PDF
EM_FORMATRANGE 把一段 RTF 文本排进虚拟画布 DC,LoadFromCanvasDC 捕获结果,如此往复直到最后一个字符

Delphi 实现

下面的代码用到 PDFlibAX_TLB 导入单元,即该库 ActiveX 版的类型库导入。窗体上放一个 TRichEdit 和一个按钮;窗体的 OnCreate 处理器负责定控件尺寸并加载 RTF,按钮点击驱动转换循环

unit MainUnit;

interface

uses
  Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls, ComCtrls, PDFlibAX_TLB, ActiveX;

type
  TForm1 = class(TForm)
    RichEdit1: TRichEdit;
    Button1: TButton;
    procedure FormCreate(Sender: TObject);
    procedure Button1Click(Sender: TObject);
  private
    function PrintRtfBox(hDc: HDC; rtfBox: TRichEdit;
      FirstChar: Integer): Integer;
  end;

var
  Form1: TForm1;
  PdfDoc: IPDFlibrary;

implementation

{$R *.dfm}

procedure TForm1.FormCreate(Sender: TObject);
begin
  PdfDoc := CoPDFlibrary.Create;
  // 按屏幕 DPI 把控件调成 A4,分页才与 DC 对得上
  RichEdit1.Width  := MulDiv(210, Screen.PixelsPerInch * 10, 254);
  RichEdit1.Height := MulDiv(297, Screen.PixelsPerInch * 10, 254);
  RichEdit1.Lines.LoadFromFile(
    ExtractFilePath(Application.ExeName) + 'document.rtf');
end;

procedure TForm1.Button1Click(Sender: TObject);
var
  Dc: HDC;
  PageNumber, LastChar, PdfDocId: Integer;
begin
  PageNumber := 1;
  LastChar   := 0;
  repeat
    // 取一个按 A4 尺寸设好的虚拟 DC
    Dc := PdfDoc.GetCanvasDC(
      MulDiv(210, Screen.PixelsPerInch * 10, 254),
      MulDiv(297, Screen.PixelsPerInch * 10, 254));
    // 把下一页 RTF 内容渲染进 DC
    LastChar := PrintRtfBox(Dc, RichEdit1, LastChar);
    // 把 DC 内容捕获为 PDF 文档
    PdfDoc.LoadFromCanvasDC(Screen.PixelsPerInch, 0);
    PdfDocId := PdfDoc.SelectedDocument;
    PdfDoc.SaveToFile(
      ExtractFilePath(Application.ExeName)
      + 'Output' + IntToStr(PageNumber) + '.pdf');
    PdfDoc.RemoveDocument(PdfDocId);
    Inc(PageNumber);
  until LastChar = 0;
  // 让控件释放它为这个 DC 缓存的格式化数据
  SendMessage(RichEdit1.Handle, EM_FORMATRANGE, 0, 0);
end;

function TForm1.PrintRtfBox(hDc: HDC; rtfBox: TRichEdit;
  FirstChar: Integer): Integer;
var
  Fr: TFormatRange;
  Dpi, PageWidthTw, PageHeightTw, NextCharPosition: Integer;
begin
  // rc 与 rcPage 用的是 twips(1/1440 英寸),不是像素:
  // 页面尺寸要用当初给 DC 和控件定尺寸的同一个 DPI 来换
  Dpi          := Screen.PixelsPerInch;
  PageWidthTw  := MulDiv(rtfBox.Width,  1440, Dpi);
  PageHeightTw := MulDiv(rtfBox.Height, 1440, Dpi);

  Fr.hdc         := hDc;
  Fr.hdcTarget   := hDc;
  Fr.rcPage      := Rect(0, 0, PageWidthTw, PageHeightTw);
  Fr.rc          := Fr.rcPage;  // 画满整页;要边距就往里缩
  Fr.chrg.cpMin  := FirstChar;
  Fr.chrg.cpMax  := -1;

  NextCharPosition :=
    SendMessage(rtfBox.Handle, EM_FORMATRANGE, 1, LPARAM(@Fr));
  if NextCharPosition < Length(rtfBox.Text) then
    Result := NextCharPosition
  else
    Result := 0;  // 表示最后一页
end;

end.

循环在做什么

PrintRtfBox 填充 TFormatRange 结构并通过 SendMessage 将其传递给 Rich Edit 控件。控件从 cpMin 开始渲染字符,当 DC 填满时停止,并返回第一个未容纳的字符的位置。当返回值等于或超过总文本长度时,说明每个字符都已经渲染完毕,该函数返回零,从而终止 repeat...until 循环

每轮迭代产出一个 PDF 文件,名为 Output1.pdf、Output2.pdf 等等。想要的是单一多页文档的话,AddToFileList 加 MergeFileList 可以事后把每页文件组装起来,也可以重构循环,让每个新页文档经 MergeDocument 并进第一份。上面的“每轮 SaveToFile 接 RemoveDocument”模式把峰值内存限制在一页内容量,对非常长的 RTF 文件很重要

容易让人绊倒的尺寸细节

LoadFromCanvasDC 的 DPI 参数告诉库你的多少个像素算一英寸:页面宽度按画布宽除以 DPI 乘 72 得出,高度同理。这个参数弄错,屏幕上图像看着正常,输出里的文本尺寸却是错的

rc 与 rcPage 的单位,是这项技术的多数 Delphi 示例都搞错的细节。EM_FORMATRANGE 读这两个矩形用的是 twips(1/1440 英寸),尽管它往里画的 DC 以像素工作。填像素值进去,控件会把文本排在按 96 DPI 小了十五倍的页面上:每轮挤出几个词,一个十页的文档被循环搅成几百份近乎空白的 PDF。用 MulDiv(Pixels, 1440, Dpi) 换算——DPI 用给 DC 定尺寸的那个——分页点才会落在画布真正结束的地方。rcPage 是整页;rc 是文本可占的区域,边距就来自把 rc 往里缩,同样用 twips。循环结束后,再发一次带 nil lParam 的 EM_FORMATRANGE,让控件释放它为这个 DC 缓存的格式化数据

PDF:EM_FORMATRANGE 的嵌套 rcPage 与 rc 矩形,两者都以 twips 给出,由当初给虚拟 DC 定尺寸的 DPI 从画布像素换算而来
rcPage 是整页,rc 是文本可用的区域;两者都以 twips 传给 EM_FORMATRANGE,底下的 DC 仍以像素工作

最后,在 FormCreate 运行时,控件必须已经附加到一个可见的表单窗口,这样在第一次调用 SendMessage 之前其窗口句柄才是有效的。如果表单尚未显示,在运行时动态创建的 TRichEdit 在渲染循环开始之前需要显式调用 HandleNeeded

处理字体和 RTF 特性

因为渲染是由 Windows Rich Edit 引擎完成的,所以字体替换遵循其用于显示和打印的相同规则。RTF 文件中引用的并在机器上安装的字体将被忠实地渲染;缺失的字体将被静默替换,这可能会改变行长和分页。对于生产环境的批量转换,这一点值得显式测试:加载使用您的 RTF 来源中每种字体的文档,并确认输出的页数与您在手动打印预览中预期的相匹配

表格、嵌入图像和大多数富文本格式特性无需额外处理就能工作,因为 Rich Edit 本来就原生渲染它们。唯一可能出乎意料的是用 twips 表达自定义段间距或首行缩进的文本:Rich Edit 内部以 twips(1/1440 英寸)度量,与 TFormatRange 里矩形同单位,而底下的 DC 按当前 DPI 以像素工作。控件绘制时自行换算,但若你以编程方式构造 RTF,就该核实自己的边距值用的也是 twips

DPI 感知和高 DPI 显示器

在 150% 缩放(144 DPI)的显示器上,毫米换像素得到的像素数比 100% 显示器上更多。PDF Library 记录你传给 GetCanvasDC 的像素尺寸,并用 LoadFromCanvasDC 里的 DPI 参数反推 PDF 里的物理页面尺寸。只要你传的 DPI 就是当初把毫米换成像素用的那个,无论显示缩放如何,输出页面尺寸都是对的

如果应用程序不感知 DPI(旧默认),Windows 会缩放屏幕 DC,高 DPI 机器上的像素计算随之出错。最省事的修法是在应用程序清单里声明 DPI 感知;之后应用程序拿到的是真实设备像素,示例传给 LoadFromCanvasDC 的 Screen.PixelsPerInch 报告的也是真实显示 DPI,而不是按 100% 缩放假设

输出结构:每页一个文件还是组合文档

上面的循环把每页写成一个单独的 PDF 文件。这是不是你想要的,取决于下游用法。报表生成系统常常要单页文件,因为它们稍后才通过合并或重排页面组装最终文档。从头就要单一 PDF 的话,库允许你在一个会话里搭出来:记下第一次 LoadFromCanvasDC 创建的文档 ID,之后每轮用 SelectDocument 选中它、以新页文档的 ID 调 MergeDocument 代替 SaveToFile,循环退出后保存一次。这免掉中间文件,是多数单文档转换场景的正确结构

PDF:在每轮写一个 PDF 文件留待后续组装,与在循环内追加页面构建单个多页 PDF 之间选择
同一渲染循环既可以喂多个独立 Output 文件,也可以喂一个不断增长的文档,以中间文件换取下游灵活性

对于大型 RTF 文件,值得在循环中添加一些进度反馈,因为转换速率大致与页数成正比,一个 200 页的文档可能需要几秒钟。repeat...until 结构很容易扩展:在每次迭代后跟踪进度条更新中的字符偏移量,使用 LastChar 除以从 RichEdit1.GetTextLen 获取的总字符数

这里展示的 GetCanvasDC 与 LoadFromCanvasDC 方法属于面向 Delphi 和 C++Builder 的 losLab PDF Library