【office2pdf】PPTX 字体解析与文本样式继承(PPTX_FONT_RESOLUTION.md)

摘要本文档记录了 PPTX 保真度问题该问题最初看起来像是布局错误但实际上是由不完整的字体和文本样式解析引起的。可见的症状是多个幻灯片上的文本块尤其是幻灯片 4 的SKILLS区域与 PowerPoint 不匹配窄标签换行方式不同标题徽章的大小和粗细不同即使文本框坐标正确某些文本在视觉上也会发生偏移根本原因不是硬编码的幻灯片几何形状。真正的问题是office2pdf没有像 PowerPoint 那样解析 PPTX 文本样式。问题PowerPoint 文本格式不仅仅由直接的 run 属性决定。对于文本框有效的样式可能来自多个 OOXML 层级a:rPr中的直接 run 属性a:pPr中的段落属性a:lstStyle中的文本主体默认值a:defPPr中的默认段落属性a:lvlNpPr中特定级别的段落属性a:defRPr中的默认 run 属性主题字体引用如mj-lt/mn-lt在修复之前PPTX 解析器主要使用直接的a:rPr和 run 上直接的a:latin值。这是不完整的。结果如下缺少直接字体设置的 run 丢失了继承的字体族、大小、颜色和粗细使用lstStyle默认值的文本框渲染的样式比 PowerPoint 弱由于有效的字体度量错误换行出现差异在回退选择方面还存在第二个问题回退顺序过于激进地优先考虑字体源排名这导致 Office 管理的字体如Malgun Gothic的优先级高于Pretendard的度量首选替代列表在这台机器上这比使用Apple SD Gothic Neo产生的换行效果更差为什么 PowerPoint 看起来正确受影响的演示文稿不仅仅依赖主题字体。它在幻灯片 XML 中包含显式的字体信息如Pretendard、Pretendard SemiBold及相关变体。PowerPoint 应用直接的 run 格式继承的lstStyle默认值跨latin、ea和cs的脚本感知字体解析当确切字体不可用时的本地回退行为office2pdf缺少了部分继承链因此生成的 PDF 出现了差异尽管原始 PPTX 在 PowerPoint 中渲染正确。修复方案1. 解析文本主体样式继承在 PPTX 解析器中添加了文本主体默认模型使文本框能够从a:lstStyle继承样式。实现引入PptxTextBodyStyleDefaults引入PptxTextLevelStyle解析a:lstStyle、a:defPPr、a:lvlNpPr和嵌套的a:defRPr在应用直接的段落/run 覆盖之前合并继承的段落和 run 样式从a:latin、a:ea和a:cs应用字体而不仅仅是直接的a:latin这使得文本框的行为更接近 PowerPoint 的有效样式模型。2. 保留度量回退顺序对于Pretendard等已知字体族的回退选择现在优先保留替换表中与度量兼容的顺序仅将源排名用作次要的判定因素。这意味着首选的替代字体族顺序是稳定的Office 管理的字体不再仅仅因为是从 Office 路径发现而自动优先于更好的度量匹配项实际的演示文稿现在回退到Apple SD Gothic Neo而不是Malgun Gothic涉及的文件crates/office2pdf/src/parser/pptx.rscrates/office2pdf/src/render/font_subst.rscrates/office2pdf/src/render/typst_gen.rs验证修复通过三种方式进行了验证对lstStyle默认 run 继承进行单元测试在 Office/系统字体混合环境下对回退顺序进行单元测试重新转换实际的 PPTX 演示文稿并进行手动视觉检查修复后的观察结果幻灯片 4 的SKILLS标签不再像之前那样换行徽章/标题样式更接近 PowerPoint重新生成的 PDF 为Pretendard回退嵌入了Apple SD Gothic Neo变体而不是Malgun Gothic剩余已知差距与文本继承无关幻灯片 17 仍然会警告不支持的hdphoto1.wdp关键经验当 PPTX 渲染不匹配看起来像文本框位置问题时不要首先假设坐标错误。在 PowerPoint 中不正确的字体解析通常会变成布局问题不同的字体族不同的粗细不同的继承大小不同的行距即使文本框几何形状正确这些差异也会改变换行和视觉对齐。