技术文章

PDF Library for Delphi:CJK 与 Emoji 文本的自动字体回退

一套用 Arial 排版的发票模板打出 "Invoice for" 之后就没了下文。文本调用返回 1,文件通过校验,提取文本却少了十个字符:北京示例科技有限公司里的每个汉字都不见了,因为 Arial 一个都没有。PDF Library for Delphi 的自动字体回退默认开启,会从已安装字体里把这些字符找出来;AddFontFallback 让你定义自己的查找顺序;再配上缺字形策略和 JSON 报告,处理任何字体都画不出来的字符

正是这种无声无息让代价高昂。一份本该有客户名称的位置却空着的 PDF 能通过所有结构检查,能在所有阅读器里打开,而且通常是被客户而不是被你的测试套件发现

为什么不受支持的文本会无声消失而不是报错?

PDF 没有“字体拒绝某字符”的概念,所以缺字形在文件层面根本不算错误。简单字体通过编码把单字节码映射到字形名;复合字体通过 CMap 把码映射到 CID,再映射到字形索引。向一个字体索要它没有的字符,你会落到字形索引零,也就是 .notdef,ISO 32000-1 §9.7.6.3 把它当作未定义字符的标准结果。大多数字体把 .notdef 画成一片空白,有些画成空心方框

无论哪种,内容流都格式良好,页面照常渲染。规范没有要求生成器在写文本操作符之前检查覆盖范围,所以跳过检查的生成器产出的是一份合规文件,只是内容悄悄丢了。这就是回退和报告必须成对出现的原因:能解决的解决掉只是半个工作,把剩下的告诉你才是另外一半——在我们看来,对任何带人名或金额的东西,这一半更重要

在 PDF Library for Delphi 中打开回退链

只有当选定字体确实缺少字符串中的某个字符时,回退才会介入,所以纯拉丁文本走正常路径,没有任何额外开销。新建的 TPDFlib 实例默认就开着自动回退,绘制代码一个额外的调用都不需要:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // 自动回退默认开启:emoji、假名、谚文、
    // 汉字和符号都会在内置候选表里查找
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = embed as a subset
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

自动回退开启时,库按每个未解析字符的文字系统挑候选。这张表是固定且面向 Windows 的:emoji 和 pictograph 先试 Segoe UI Emoji,再试 Segoe UI Symbol、Arial Unicode MS;假名先试 Yu Gothic;谚文先试 Malgun Gothic;统一汉字区先试 Microsoft YaHei,再试 Microsoft JhengHei、Yu Gothic、Malgun Gothic 和 SimSun;数学和技术符号归 Segoe UI Symbol 和 Cambria Math。其余一切落到一个以 Nirmala UI 和 Segoe UI 打头的宽名单上

你用 AddFontFallback 注册的字体会在那张内置表之前按加入顺序尝试。SetAutomaticFontFallback(0) 只关掉内置表:显式链条继续生效,当你要求输出只用你批准的字体、别的什么都不用时,选这个设置。AddFontFallback 会忽略已在列表中的名字并返回其 1 起算的位置;ClearFontFallbacks、RemoveFontFallback 和 GetFontFallbackCount 让你能在文档之间重建链条

汉字统一陷阱:共享字符谁说了算?

中日韩三种文字在 Unicode 里共享大部分汉字,但每个 locale 对其中许多字期待不同的字形。“直”或“骨”的码位在东京地址和北京地址里是同一个,母语读者期待的形状却不是。回退链只能回答“哪个已安装字体有这个码位的字形”,而每个 CJK 字体都有,所以谁排在前头谁就赢下所有共享字符

自动表把 Microsoft YaHei 排在汉字第一位。这对简体中文没问题,对日语就是错的。那张发票上的日文地址会出现一行里假名由 Yu Gothic 绘制(假名把查找先送到日文字体)、汉字由 YaHei 按中式字形绘制的混排。什么都不缺,报告空空如也,日本读者却一眼看出不对劲

我们的建议是:汉字不要依赖自动顺序,而是按文档的 locale 构建显式链条。你通常早就知道这个 locale——客户档案里写着,或者模板语言摆在那:

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // emoji、符号以及上文未覆盖的文字系统仍然
  // 走内置候选;在这里传 0 可禁止这一点
  Lib.SetAutomaticFontFallback(1);
end;

每个文档调一次,在第一条 DrawText 之前。显式列表内部的顺序同样要紧:第一个覆盖某字符的字体赢,所以 Arial Unicode MS 这种泛 Unicode 字体即使要放也应放在末尾。放最前面它几乎会画走一切,你精心挑选的各文字系统专用字体永远轮不到上场

回退以整个簇为单位

PDF Library for Delphi 按字素簇决定回退,所以一个簇永远由一个字体绘制。一个天城文音节、一个带肤色修饰符的 emoji、一个带组合附标的基字母:这些在屏幕上都是单个单元,其内部的整形决策来自某一个特定字体里的表。半个簇来自 Arial、半个来自回退字体,会放出一个技术上存在、视觉上残废的字形——可以说比空白更糟

选定字体先对字符串整形。只有解析成字形零的簇才去找别的字体,而解析到同一字体的相邻簇合并成一个 run 绘制,所以十个汉字的中文名变成一个 YaHei run,而不是十次独立的字体切换。从右到左的顺序同样保留:阿拉伯或希伯来文文本中的回退 run 坐在双向算法给它安排的位置上。同一套整形机制也驱动着日文与中文的竖排

PDF Library for Delphi 回退链示意:一个 CJK 簇 run 在主字体 Arial 上落空,由第一个覆盖的回退字体 Microsoft YaHei 绘制,未被覆盖的簇走报告或中止策略
这个簇 run 从主字体落到第一个覆盖的回退字体,只有真正用到的字体才会嵌入;任何字体都画不了的簇按缺字形策略处理:报告并继续,或以错误 521 中止

缺字形该不该拦下整份文档?

取决于文档的用途,PDF Library for Delphi 用 SetMissingGlyphPolicy 把选择权交给你。PDF_MISSING_GLYPH_REPORT 是默认值:文本操作照常进行,任何字体都画不了的字符从输出中丢弃,每一个都记录在案。PDF_MISSING_GLYPH_ABORT 在任何东西落到页面上之前就否决整个文本操作,DrawText 返回 0,错误码为 521(PDFLIB_ERROR_MISSING_GLYPH)

内部批量报表选报告策略并把缺口记进日志,今天一份略有缺漏的报表好过没有报表。合同、发票、证书以及任何带人名或公司名的东西选中止。客户名称里丢一个字符是你想在自己的流水线里逮住的缺陷,而且中止发生在写页面之前,页面上不会留下半行残字

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // 读取它同时会把它重置为 0
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

注意那个局部变量。LastErrorCode 读取即清零,所以一处写 Lib.LastErrorCode = 0 判断、另一处又拿 Lib.LastErrorCode 记日志的代码,记下来的永远是 0。读一次,把值留住

每条报告事件带有页码、字符串内的 UTF-16 索引、十进制和 U+XXXX 形式的码位、被选中的字体及其类型、以及撞上问题的那个 API 调用。有了这些,支持工单点名的是具体字符而不是描述症状。valid 标志只在没有任何事件时为 true,这让它在批处理作业里成为一个廉价的闸门

库只保留最近 256 条事件并丢弃更旧的,所以一份满是画不出来的文本的文档不会把诊断变成内存问题。事件在同一个 TPDFlib 实例上跨文档累积;想要每个文件一份报告,就在每个文档前调 ClearMissingGlyphReport,或者用 documentIndex 字段区分它们

字母上中止,装饰上宽容

对整份文档用单一策略有时太一刀切。一张快递标签可能在收件人名字旁边带一个装饰性 emoji,你宁愿丢掉 emoji 也不想拒掉整张标签。OnMissingGlyph 事件对链条中任何字体都画不了的每个字符触发,以当前策略作为默认动作,并允许按码位改写:

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // 图形符号和杂锦符号属于装饰:丢弃并记录
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // 字母和数字绝不能凭空消失
end;

// 接上事件
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

事件在回退充分尝试过之后才触发,所以它看到的只是这台机器上真正无法解析的字符。无论处理器选择哪种动作,每一个都照样进入 JSON 报告

测量、嵌入与部署

GetTextWidth 经历与 DrawText 完全相同的逐簇回退决策。听起来理所当然,但这恰恰是自造回退层最容易翻车的地方:它们给绘制调用打补丁,测量却还留在主字体上,于是每个右对齐的合计数和表格列都是按与页面实际不符的宽度算出来的。在这里,绘制前量好的字符串占的就是量出来的宽度,回退 run 也算在内——这正是可以放心到处开着回退,而不只在人工审计过的模板里开的原因

中止策略下有个后果:测量撞上无法解析的字符时,GetTextWidth 返回 0 并设置错误 521。用宽度做除法或拿它定单元格尺寸的布局代码,用这个数之前先检查这一点

回退字体只在真的画了东西时才嵌入。链条里从未解析过簇的字体不给文件增加任何字节;画过的则以子集形式嵌入它画过的那些字形。一份在 5000 个拉丁字符里夹一个汉字的文档,只带一个 Han 字形,而不是几兆的 CJK 字体;文件体积优化与字体子集化讲了子集如何构建。正因如此,配一条覆盖你服务的所有 locale 的长链条代价很低,每份 PDF 只为自己用到的部分买单。别处生成的、引用了从未嵌入字体的文件是另一种修复,见给现有 PDF 嵌入缺失字体

部署上的坑容易被忽略。回退解析依赖跑你代码的那台机器上装了哪些字体,一台装满 Office 的开发工作站比精简的服务器镜像或容器多得多。Yu Gothic 或 Microsoft YaHei 不在那儿,链条就无从回退。在目标服务器上跑一份带汉字名字、谚文名字和一个 emoji 的文档,读一读 JSON 报告:那里一个空的 events 数组比你自己桌面上的任何测试都有说服力。把你依赖的字体随包发布,并确认许可证允许嵌入

同一套回退链、缺字形策略和报告也通过 DLL 和 ActiveX 版本对外提供,C#、C++ 或脚本调用者用同样的调用配置它们。参考文档与下载见 PDF Library for Delphi 产品页