上个月在处理一个PDF重排项目时我遇到一个诡异的问题文档只有几十页字符提取和坐标获取全部正常但只要把文本按行重排中文就全部叠在一起英文却安然无恙。一开始怀疑是编码问题后来追到最后才明白罪魁祸首是字体里的宽度数组——准确地说是我的代码压根没有读取它。PDF在排版时对每个字符下一步位置的判断完全建立在宽度数组之上因为每个字形画完后光标要往右推进多少才能让下一个字不重叠也不稀散这个推进量就来自宽度数组。这篇文章就把我对“Pdfium如何处理宽度数组”的完整理解写下来包括内部数据结构、读取接口的能力边界、容易踩的单位换算坑以及拿宽度数据做二次开发的实用技巧适合正在做PDF文本重排、坐标标注、版面分析或自定义渲染的开发者参考。1. 宽度数组PDF文本定位的隐藏基石1.1 一个浮点偏移引发的连锁错位先还原一下那个问题的现象。某文档里有一段中文和一段英文混排英文提取后按行重排位置几乎一致中文重排后前一字的右边缘直接压到后一字的左边缘整行字全部重叠。英文正常、中文异常这个现象本身就说明问题不在编码而在字体英文大多走TrueType简单字体宽度数组在字体字典里直接可见Pdfium能轻松读到中文走的是Type0复合字体CIDFont它的宽度存储路径完全不同一旦路径断了就会回退到默认宽度250千分单位而中文字形的真实宽度普遍在900到1000这个范围。实际排版时250和1000的差距一乘上字号错位就会变得非常明显。为什么宽度这么关键我们在屏幕上看到的每个字符本质上是“画”上去的。画完一个字形之后下一个字的位置由当前字形的推进量advance width决定。PDF的内容流里Tj运算符只是把一串字符放在当前位置真正决定它们横向间隔的是每个字形对应的宽度数据。字体负责提供形状宽度数组负责提供排版依据两者缺一不可。如果宽度数据丢失或错误轻则文字重叠重则整段布局被打乱连换行位置都会跟着变化。页面坐标、字符解析都没问题但重排结果错乱说明问题出在排版数据这一层——我拿到了形状数据却没有把宽度数据一起带走。这就像买菜谱只拿食材清单、不拿用量说明做出来的菜当然不对。1.2 PDF里宽度数据到底存在哪在PDF文件层面宽度数据主要藏在两个地方一是字体字典直接嵌入宽度表二是嵌入字体文件内部的宽度度量。简单字体Type1和TrueType通常直接在字体字典中放一个Widths数组同时用FirstChar和LastChar标明数组覆盖的字符编码区间。数组下标是从FirstChar开始的字符编码c对应的宽度取Widths[c - FirstChar]。如果目标字符不在区间内就回退到默认宽度简单字体里一般用字体自带的MissingWidth或给一个固定兜底值不同解析器实现有差异。复合字体Type0尤其带CID的走的是另一套结构字体字典里先放一个DW值作为默认宽度再放一个W数组。W数组里可以按CID区间写多种格式比如[3 [500 600 700]]表示CID为3的字宽度是500CID为4的字宽度是600CID为5的字宽度是700再比如[10 15 800]表示从CID 10到CID 15这六个字形宽度统一是800。我一开始没找到是因为习惯性地只找Widths这个关键字忽略了Type0字体用的是W而不是Widths更忽略了那些没有显式宽度表、只能靠嵌入字体文件内部数据才能拿到宽度的情形。这些差异在Pdfium内部都有兼容处理但它兼容的结果不一定符合你对“宽度”这个概念的预期后面会详细展开。1.3 Glyph单位、PDF单位与像素之间的换算宽度数组里的数值不是能直接当像素用的数字。这里有三层单位搞混了后面全是坑。第一层是字形设计单位Glyph Unit字体文件内部用的常见取值有1000、2048甚至有些字体用100。这一层只在字体文件内部有意义。第二层是PDF千分单位PDF规范规定字体宽度以千分之一em为单位也就是把1em通常等于字号大小等分成1000份宽度数组里的999表示这个字形占0.999个em。第三层才是用户空间坐标也就是页面上真实使用的“点”。从PDF千分单位到用户空间需要乘以字号FontSize再到像素还要乘一个DPI/72的缩放因子。单位层级常见范围到下一层的换算典型场景Glyph Unit100 / 1000 / 2048除以units_per_em再乘1000读取字体文件内部hmtx、CFF表PDF千分单位01000左右乘以字号Pdfium宽度接口、Widths/W数组用户空间点与页面尺寸相关乘以DPI/72FPDFText_GetCharBox输出、页面坐标如果走FPDFText_GetCharBox拿字符边界框API内部已经帮你做完了上述换算但如果你直接操作宽度数组、自己拼排版就一定要记得在拿到原始宽度后乘字号。我之前拿重排结果跟渲染结果对比时字号越大偏差越明显正是这个转换漏掉了。2. Pdfium读取宽度的内部机制与公开API2.1 从FPDFPage到CPDF_Font的解析链路Pdfium加载PDF文档时并不是把所有字体和宽度数据一股脑塞进内存而是按需解析。调用FPDF_LoadDocument打开文档后页面对象处于“懒加载”状态直到调用FPDF_LoadPage这一页的内容流才会被解析遇到文本对象时才会定位它引用的字体资源。在这个过程中字体对象在内部会被构造成CPDF_Font的子类简单字体走CPDF_SimpleFont复合字体走CPDF_CIDFont。这两个类内部都维护了宽度相关成员。CPDF_SimpleFont里有一个m_Widths数组构建时会把字体字典里的Widths和FirstChar/LastChar读进去CPDF_CIDFont则维护了类似区间映射的结构再加一个默认宽度字段。理解这条链路对调试很重要你拿到的字体对象宽度数据是否已经就绪取决于它是否被“加载”过。某些场景下字体对象可能只有一个外壳内部的宽度表还没解析这时去查宽度会得到默认值。一个常见的经验是在调用渲染或文本提取相关接口之前可以先让页面做一次完整的渲染哪怕输出到一张小尺寸位图这样字体解析逻辑基本都会走完后续读宽度会更可靠。2.2 三个常用API的能力边界Pdfium的公开API里跟宽度读取直接相关的按使用频次排大概是这三类。第一类是FPDFText_GetCharBox它返回一个字符在页面上的边界框左右上下坐标。严格说这不是“宽度数组”但它包含了渲染结果层面的宽度信息是大多数二次开发最先碰到的接口。优点是已经处理完所有单位换算直接得到页面坐标缺点是它给的是字符实际占用方框不等同于排版推进量。如果要模拟光标推进用它右边界减左边界也可以但要注意边界框可能包含字距调整或字形溢出跟语义上的advance width不完全一致。第二类是按字形ID查宽度的单字形接口。它返回单个字形在“字体空间”下的宽度这个字体空间是经过字体内部度量矩阵缩放后的千分单位通常等于PDF标准宽度。它的粒度比GetCharBox细适合做重排但要自己额外获取字号并做乘法。要注意接口名在不同版本中略有变化有的版本叫法完全不同使用前先查一下你手上版本的头文件。第三类是批量获取宽度数组的接口能一次性把整个宽度表拉出来减少逐字符调用开销。注意它的语义是返回字体对象的原始宽度表形状可能是稀疏数组或区间表你需要自己建立从字符编码/CID到数组下标的映射不能假设数组从0开始连续排。我的建议是做快速原型用第一类做重排引擎用第三类批量接口第二类只适合临时调试。因为逐字符调用的封装和上下文切换开销在几万字文本的场景下会让性能肉眼可见地变差后文有具体数据。2.3 CID字体与Simple字体的宽度存储差异同样是“宽度数组”Simple字体和CID字体的存储与读取路径差得很远把两者搞混是新手常见错误。Simple字体Type1、TrueType的字符编码通常是单字节宽度数组按CharCode索引区间连续、大小固定最多256个。Pdfium构建这类字体时会直接把Widths数组拷贝进内存后续可以做到O(1)查找。缺点是一旦字符不在FirstChar和LastChar之间就只能回退到默认宽度很多老PDF里乱码字符或私有区字符都会被给出一个奇怪的默认宽度。CID字体Type0的字符编码是双字节起的靠CMap把CharCode映射到CID再通过字体对象的内部数据结构把CID映射到宽度。宽度存储是按“CID区间”组织的一个W数组可以覆盖多个不连续区间所以Pdfium在CPDF_CIDFont里会把这些区间解析成一个索引结构查询时先找区间再计算区间内偏移。对比项Simple FontType1/TrueTypeCID FontType0宽度表关键字Widths / FirstChar / LastCharDW / W索引依据CharCode单字节CID经CMap映射数组形态连续数组长度一般≤256区间表可稀疏、可重叠查询复杂度O(1)区间查找通常为对数级常见遗漏默认宽度回退W区间边界、编码映射不一致从实测看Simple字体的宽度查询基本是一条直线CID字体在区间多、字形多时会有明显的查找开销但Pdfium做了缓存普通文档几万次查询差异不大。真正要留神的不是性能而是CID的获取方式同一个CharCode在不同CMap下映射到的CID可能不同从而查到不同宽度。如果你做文本处理时拿到的“字符编码”和Pdfium内部用的“字符代码”不是同一个宽度表对不上就非常正常。3. 手把手读取宽度数组并建立缓存3.1 读取流程与代码骨架先给一个能跑的流程。我整理的是C环境下、不走外部库的常见写法核心步骤是打开文档、加载页面、定位页面对象、拿到字体句柄、读取宽度。// 1. 打开文档与页面 FPDF_InitLibrary(); FPDF_DOCUMENT doc FPDF_LoadDocument(filePath, nullptr); FPDF_PAGE page FPDF_LoadPage(doc, 0); // 2. 遍历页面对象找第一个文本对象拿字体句柄 int objCount FPDFPage_CountObjects(page); for (int i 0; i objCount; i) { FPDF_PAGEOBJECT obj FPDFPage_GetObject(page, i); if (FPDFPageObj_GetType(obj) FPDF_PAGEOBJ_TEXT) { // 这里演示只拿第一个文本对象真实场景需要遍历全部 FPDF_FONT font FPDFTextObj_GetFont(obj); // 版本差异较大以你的版本头文件为准 break; } } // 3. 批量读取宽度不同版本接口名有差异这里按语义写 int widthCount 0; const unsigned int* widths GetFontWidths(font, widthCount);读出来之后不要直接对widths数组按“字符的Unicode码”去索引因为它的下标体系可能是CharCode、GID或CID取决于字体类型。我一般会再拿当前文本对象的实际编码信息建立一张本地映射表。如果批量接口在你的Pdfium版本里不可用退而求其次的写法是遍历某个字符区间逐字符调单字形宽度接口。但这种方式在Type0字体上通常会漏掉那些“没有显式宽度、需要回退默认宽度”的字符你需要额外结合DW值做兜底。3.2 Fallback分支DefaultWidth与W数组区间宽度数组天然是稀疏的做读取时必须写清楚回退逻辑否则就会拿到一个“看似正常其实错误”的默认值。我用的回退逻辑是这样double getCIDWidth(const FontWidthTable table, uint32_t cid) { // 先查CID是否落在某个W区间内 auto it table.w_interval.find(cid); if (it ! table.w_interval.end()) { return it-second; } // 不在任何W区间回退到DW默认宽度 return table.default_width; }看起来简单但实际项目里两个细节很容易翻车。第一个W数组里同一个CID可能会出现两次比如某个区间的端点同时被下一个区间覆盖。多数解析器按“先到先得”处理但PDF规范并没有严格禁止重复我建议读取时主动做“后者覆盖前者”或者至少打一条日志否则排查时很难发现是哪个区间生效导致宽度偏大或偏小。第二个DefaultWidth的默认值。规范建议值是0还是250在Pdfium内部CIDFont的默认宽度往往初始化为0但如果字体字典里没有DWPDF阅读器通常会按固定宽度字体的惯例给一个默认值常见实现是250。你自己代码里回退时要注意“标准默认值”和“解析器默认值”可能不一样这个差别会直接反映在字体缺失时文字的稀疏或重叠上。3.3 缓存键的设计字体句柄变体宽度数据在文档生命周期内基本不变但每次调用接口重新读取都有开销所以一定要缓存。缓存键的设计上我踩过一个坑直接用字体句柄当键。原因在于同一个PDF文档里同一套物理字体可能以多个不同的字体句柄出现——页面A和页面B各自引用了不同资源目录里的同名子集。它们的宽度表内容可能完全相同但句柄不同导致缓存命中率上不去。反过来同一个句柄在字体加载前后内部字段的可用性也可能变化所以更好的做法是“字体标识名子集标识”作为键。我最终用的缓存结构是一个全局哈希表键是编码后的字符串值是一份不可变的宽度表快照。大文档几千页、几万字体引用下这个缓存在内存上大概能省下90%的重复解析时间效果非常明显。缓存时还要注意线程安全Pdfium本身对并发渲染有保护但你自己的缓存数据结构必须自己做加锁或线程本地化否则高并发场景下哈希表的并发写会直接崩。提示缓存宽度表时尽量把“宽度来源”也一起记录下来。是来自PDF的W数组还是来自字体文件内部的hmtx表这个信息在排查宽度不一致问题时价值极高。4. 宽度数据对不上的三类真实案例4.1 案例一Type3字体的FontMatrix忘乘了先讲一个特征最明显的案例。某文档中有一段装饰字体Type3重排时字符间距被放大了大约8倍越往后错位越严重。检查单字符宽度是正常的千分单位数值检查字号也取到了正确值但重排结果就是不对。后来翻到字体对象内部的FontMatrix才明白Type3字体的宽度单位不是固定的千分之一em而是由FontMatrix定义。这个字体的FontMatrix是[0.125 0 0 0.125 0 0]也就是说字体空间下的1个宽度单位在文本空间里只有0.125个单位。宽度接口返回的是字体空间值没乘这个矩阵就直接用了等于把字形放大了8倍。处理方式很简单拿到宽度后先查一下该字体是否为Type3是的话就把宽度乘FontMatrix的比例项。Pdfium渲染层内部就是这个逻辑但公开接口并不会替你完成这步因为调用者可能想拿原始字体空间数据做别的分析。这个案例也提醒我处理任何字体数据前先确认它的类型和度量矩阵而不是想当然地用一套逻辑通吃。4.2 案例二CFF/OpenType字体的隐藏宽度表另一个项目里我用某个工具生成的PDF做处理文档里的中文总是比预期窄窄了大约一半。Widths数组读出来没有异常但字体是OpenTypeCFF子集。排查过程比较曲折。先看W数组找到了范围和数值本身都像合理。但是把每个字符的边界框用GetCharBox打出来对比发现实际渲染宽度比W数组给的宽度小很多。也就是说W数组里的数字和渲染引擎实际使用的数字不一致。继续追发现根源在字体文件内部那个生成工具在子集化时把CFF字体内部的实际宽度度量改了但PDF的W数组没有同步更新。Pdfium在解析CIDFont时做了一步“尝试用字体文件内部度量校正宽度”的逻辑——如果字体内部有可用的宽度数据就会覆盖W数组里的值。这一步在不同版本里行为不一致有的版本完全不看字体内部数据有的版本只要检测到就使用。这个案例给我的教训是不要假设“Pdfium返回的宽度一定来自PDF的宽度数组”。它有自己的一套优先级而且这套优先级在不同版本、不同字体格式下并不统一。调试时如果发现返回值和字典里的W不一致别急着怀疑自己的读取代码先确认是不是字体内部宽度表在覆盖。4.3 案例三子集化后PDF宽度表与字体内部不一致和案例二类似但更隐蔽的情况出现在TrueType子集字体上。字体字典里的Widths数组只覆盖了被保留的字符子集没有覆盖的空洞字符应该走默认宽度但Pdfium在某些场景下会返回字体内部hmtx表中的值即使该字符没有被子集化进来。这会导致一个奇怪的现象同一个CharCode在页面A和页面B上出现字体句柄不同页面A用的子集包含该字符页面B用的子集不包含Pdfium给宽度却是同一个数字——因为字体对象内部从hmtx里能查到但PDF宽度表里查不到。如果自己的代码完全按“PDF宽度数组”做缓存就会出现部分页面错位。我的处理是把“字体对象实际能提供的宽度来源”也作为一个维度记录下来而不是只记录宽度值本身。这样重排时至少知道哪些宽度是可靠数据、哪些是解析器兜底必要的时候允许业务层做降级处理。5. 把宽度数组用好重排、对齐与性能优化5.1 用累计宽度实现文本重排做PDF文本重排时最朴素也最实用的做法是把原页面里每个文本对象解析出来按阅读顺序做累计宽度求和。伪代码逻辑如下// 把一行里的字符按原有顺序排列用宽度数组累加出每个字符的起始X double xCursor lineStartX; for (int i 0; i lineChars.size(); i) { lineChars[i].newX xCursor; double w getWidthForChar(lineChars[i].cid, font); // 如果是Type3记得乘FontMatrix // 如果是垂直文本这里用的是Y方向但原理相同 xCursor w * fontSize * scale; }这个逻辑对所有字体通用前提是你已经拿到了正确的宽度。要注意的是行内可能会出现多个文本对象比如一个字一个Tj中间还夹杂着TJ数组中的偏移量。如果只按“每个文本对象的第一个字符对齐”行内字符就会错位。我通常的做法是先按文本对象在页面上的坐标排序再在每个文本对象内部用它的起始坐标加上累计宽度去计算每个字符的绝对位置。这样即使原PDF把一句话拆成几十个Tj重排后也能拼回完整的一句话。5.2 TJ数组里的偏移量与精确对齐宽度数组只解决“默认推进”但PDF内容流里真正的排版还包含TJ运算符中的数字偏移。看下面这段内容流BT /F1 12 Tf 72 720 Td [(H) 20 (e) -10 (l) 0 (l) 0 (o)] TJ ET这里的20、-10、0都是额外的字间距调整。H之后的光标推进等于H的宽度加上20e之后的光标推进等于e的宽度减10。如果只拿宽度数组累积完全忽略这些偏移最终重排出的文本会和原文的视觉密度差很多。很多初学者以为字符坐标直接拿边界框就完事了但在做“重排”这种需要重新生成布局的场景里TJ偏移恰恰是还原原作者排版意图最关键的信息。Pdfium在解析内容流时会把Tj和TJ统一转成带偏移的字符对象序列内部是可以拿到每个字符偏移量的但公开接口暴露得不完整。如果项目要求重排结果与原版“视觉上一致”就得考虑在文本对象解析层自己读TJ数组把偏移量合并进宽度计算。5.3 减少API调用次数与线程安全最后说一点性能上的实操经验。宽度数组看似是小事但在大文档场景下会变成性能瓶颈。我做过一次压测某文档包含约22万字符如果用逐字形接口查宽度总耗时在单线程下接近4秒如果先批量拉取宽度数组再在本地做映射耗时可以压到0.3秒以内差距在13倍左右。具体优化手段有三个。第一按字体聚合先把页面所有文本对象按字体分组同一字体的宽度表只拉一次。第二拿到宽度表后不直接跨接口查找而是把字体内部的CharCode/CID到宽度的映射摊平到本地容器里用O(1)查找。第三利用好Pdfium的自带缓存同一字体对象在多次查询时内部其实有缓存但那是它自己的缓存不等于你的业务代码缓存该自己建的映射还是要建。线程安全方面Pdfium从不同页面拿到的字体句柄在并发渲染时是受保护的但如果你把字体句柄保存下来、在多个线程里同时查询就可能踩到未定义行为。稳妥的方案是在单线程环境下把需要的宽度表全部提取并拷贝成自己的结构之后并发重排阶段只用自己的数据不再碰Pdfium对象。最后再分享一个我养成的习惯接到PDF处理任务时先写一个十几行的小工具把文档里出现过的所有字体、字符编码、宽度数组和实际渲染宽度拉出来打印一份对照表。有了这张表后面所有关于重排、对齐、标注的坑都能快速定位到是字体解析层还是业务层的问题。宽度数组看着只是PDF解析里一个不起眼的角落但它串起了字体、排版、坐标系统、单位换算、缓存乃至并发安全把这块啃下来比临时查一百次文档都有用。