跳轉到

字型管理

FontRegistry 是 NextPDF 字型管理的中央倉庫，在 Process 層維護已載入字型的快取，避免重複解析字型檔案。支援 TrueType、OpenType（CFF）、Type 1 與 PDF Base 14 標準字型。

載入 TrueType / OpenType 字型

use NextPDF\Typography\FontRegistry;

// 透過 Process 取得 FontRegistry
$registry = $process->fonts();

// 從檔案載入
$registry->loadFromFile(
    path: '/path/to/NotoSansCJKtc-Regular.otf',
    alias: 'NotoSansCJK-Regular',
);

// 從目錄批量載入
$registry->loadFromDirectory(
    path: '/path/to/fonts/',
    extensions: ['ttf', 'otf'],
);

Base 14 標準字型

PDF 規格定義了 14 種標準字型，無需嵌入即可使用：

use NextPDF\Typography\Base14Font;

// Helvetica 系列
$document->text()->write(
    text: 'Standard font text',
    position: Position::at(x: 20.0, y: 50.0),
    style: FontStyle::create(fontFamily: Base14Font::Helvetica),
);
字型名稱 類型
Helvetica Sans-serif
Helvetica-Bold Sans-serif Bold
Helvetica-Oblique Sans-serif Italic
Helvetica-BoldOblique Sans-serif Bold Italic
Times-Roman Serif
Times-Bold Serif Bold
Times-Italic Serif Italic
Times-BoldItalic Serif Bold Italic
Courier Monospace
Courier-Bold Monospace Bold
Courier-Oblique Monospace Italic
Courier-BoldOblique Monospace Bold Italic
Symbol Symbol
ZapfDingbats Dingbats

字型嵌入策略

use NextPDF\Typography\EmbedStrategy;

$registry->loadFromFile(
    path: '/path/to/font.ttf',
    alias: 'MyFont',
    embedStrategy: EmbedStrategy::Subset,  // Subset | Full | Reference
);
策略 說明 適用場景
Subset 僅嵌入使用到的字符（預設） 一般文件，最小檔案大小
Full 嵌入完整字型 可編輯 PDF、表單
Reference 不嵌入，僅引用 內部系統，確定閱讀器有安裝字型

Type 1 字型

// 載入 Type 1 字型（.pfb + .afm 配對）
$registry->loadType1(
    pfbPath: '/path/to/font.pfb',
    afmPath: '/path/to/font.afm',
    alias: 'MyType1Font',
);

字型驗證

// 檢查字型是否支援特定 Unicode 字元
$registry->supportsCodepoint(
    alias: 'NotoSansCJK-Regular',
    codepoint: 0x4E2D, // 中
);

// 列出已載入的字型
$fonts = $registry->listLoaded();

字型替換（Fallback）

// 設定字型替換鏈：主字型 → 備用字型1 → 備用字型2
$registry->setFallbackChain(
    primary: 'Helvetica',
    fallbacks: ['NotoSansCJK-Regular', 'NotoSansArabic-Regular'],
);

參見