字体工具

速览

NextPDF Pro 检查嵌入的字体程序，按标准命名约定识别子集字体，并生成一份带有预估体积影响的结构化反子集化（de-subsetting）计划。

可用性与授权

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并通过 Pro 层级的授权信封激活。缺少该权益的部署不会加载此能力的相关类。比较各版本并获取授权。

没有任何按功能授权标志对此模块设卡。只要安装了 nextpdf/pro，Font Tools 相关的类即可使用。

安装

composer require nextpdf/pro:^3

概念概述

PDF 中的子集字体只嵌入文档所使用的字形。按约定，它们的 /BaseFont 名称会带有一个六字母的大写标签，后跟 +，例如 ABCDEF+Arial。NextPDF Pro：

• 检测子集。 FontDesubsetter 扫描原始 PDF 数据中的 /BaseFont 条目，识别子集前缀模式，并将每个条目报告为一个 SubsetInfo 值对象，包含原始字族名称、子集字形数、完整字形数和编码。
• 规划反子集化。 DesubsetPlan 收集那些拟用完整字体程序替换的目标子集字体，并报告一个预估的字节体积增量，让你在动手前判断反子集化是否值得为之付出文件体积的代价。

Font Tools 是一个分析与规划层。它描述存在什么、以及反子集化会带来多大代价；它本身并不重写字体程序。

为何如此设计

重写一个嵌入的字体程序才是既困难又有风险的部分。字形轮廓、hinting 和 cmap 表都必须保持一致，一个失误就会破坏渲染。因此 NextPDF Pro 把廉价、安全的工作——清点与代价预估——与那项昂贵的重写分开。扫描器只读取字节；它从不解析或执行字体程序，因此保持确定性且无副作用。字形数和体积增量被刻意标注为启发式估算，这样容量判断才会诚实，而不是去信任一个模块无法测得的数字。这让你在采购完整字体程序之前，先权衡反子集化是否值得付出代价。

设计背景：字体：困难的那部分。

API 接口

类	职责
FontDesubsetter	扫描 PDF 数据并报告子集字体条目。
SubsetInfo	一个被检测出的子集的不可变描述。
DesubsetPlan	目标子集加预估体积增量。

代码示例 —— 快速上手

use NextPDF\Pro\FontTools\FontDesubsetter;

$subsets = (new FontDesubsetter())->analyzeSubsets($pdfBytes);
foreach ($subsets as $info) {
    echo $info->baseFont . ': ' . $info->subsetGlyphCount . " glyphs\n";
}

代码示例 —— 生产环境

use NextPDF\Pro\FontTools\FontDesubsetter;

$desubsetter = new FontDesubsetter();
$subsets     = $desubsetter->analyzeSubsets($pdfBytes);
$logger->info('fonttools.scan', ['subset_count' => count($subsets)]);

边界情况与注意事项

• 扫描器会将不带六字母前缀的 /BaseFont 报告为非子集条目，而不是跳过它。
• 预估的体积增量是基于每字形平均字节数的启发式估算，而非实测值。
• 检测基于 /BaseFont 条目的字节表示进行；加密或高度压缩的对象流可能需要先解码。

性能

子集扫描随 PDF 字节长度呈线性。规划随检测到的子集数量呈线性。

安全说明

Font Tools 只读取结构性元数据。它不执行字体程序，也不解析外部字体引用。

一致性

行为	引用	状态
子集字体命名约定	ISO 32000-2 §9.9.2	已对齐（释义）

行为契约

• FontDesubsetter::analyzeSubsets() 扫描原始 PDF 数据中的 /BaseFont 条目，识别“六字母大写加 +”的子集前缀，并将每个条目作为一个不可变的 SubsetInfo 返回，包含原始字族名称、子集字形数、完整字形数和编码。
• 不带子集前缀的 /BaseFont 会被报告为非子集条目，而不是被跳过。
• DesubsetPlan 收集拟替换的目标子集，并基于每字形平均字节数报告一个预估的字节体积增量 —— 这是一个启发式估算，而非实测值。
• 这是一个分析与规划层。它报告存在什么、以及反子集化会带来多大代价；它不重写字体程序、不执行字体程序，也不解析外部字体引用。

Enterprise 边界说明

Enterprise 不改变 Font Tools 的行为。Enterprise 增加了更高层级的功能，单独编写文档；它们对于子集检测或反子集化规划并非必需。

Core 回退/替代方案

NextPDF Core 的开源字体管线处理基础字体嵌入。子集核算和反子集化规划是 Pro 的新增内容。参见 /modules/font/。

发布边界

本页仅描述外部可观察的行为以及受支持的公共 API 接口。内部命名空间路径、辅助类、机制表、运行手册文件名和工单前缀均不在范围内。

另请参阅

• Font Tools —— 深度参考 —— API 契约、行为与失败模式。
• Optimizer —— 文件体积优化。
• Core font module —— 开源字体处理。