跳轉到

Typography API

FontRegistry

namespace NextPDF\Core\Typography;

final class FontRegistry

程序級別的字型 Registry。初始化成本高（字型索引），應在程序啟動時建立一次並共享。

工廠方法

/** 建立空白的 FontRegistry */
public static function create(): self

字型管理

/**
 * 從檔案路徑註冊字型。
 *
 * @param non-empty-string $path  字型檔案的絕對路徑（.ttf / .otf / .woff2）
 * @param non-empty-string $alias 字型別名（在 TextRenderer 中使用此名稱）
 * @throws FontLoadException      若字型檔案無效或格式不支援
 */
public function registerFont(string $path, string $alias): self

/**
 * 遞迴掃描目錄，自動以檔名（不含副檔名）作為別名。
 *
 * @param non-empty-string $directory 字型目錄絕對路徑
 * @param list<string>     $extensions 允許的副檔名（預設：ttf、otf、woff2）
 */
public function registerDirectory(
    string $directory,
    array  $extensions = ['ttf', 'otf', 'woff2'],
): self

/**
 * 查詢已註冊的字型。
 *
 * @param non-empty-string $alias
 * @throws FontNotFoundException
 */
public function get(string $alias): RegisteredFont

/** 取得所有已註冊字型的別名列表 */
public function aliases(): list<non-empty-string>

/** 是否已註冊指定別名 */
public function has(string $alias): bool

/** 字型數量 */
public function count(): int

RegisteredFont

final readonly class RegisteredFont
{
    public string          $alias;
    public string          $path;
    public FontMetrics     $metrics;    // Ascender、Descender、CapHeight 等
    public list<string>    $supportedScripts;  // 支援的 Unicode Script
    public bool            $hasKerning;
    public bool            $hasVariations;     // OpenType Variable Font
}

FontSubsetter

namespace NextPDF\Core\Typography;

final class FontSubsetter

/**
 * 為指定的字元集生成字型子集。
 *
 * @param RegisteredFont      $font       來源字型
 * @param list<int>           $codepoints 實際使用的 Unicode 碼點
 * @return FontSubset
 */
public function subset(RegisteredFont $font, array $codepoints): FontSubset

/** FontSubset 包含子集化後的字型二進位資料 */
public function subsetData(): string
public function glyphMap(): array<int, int>  // Unicode → GID 映射

BiDiResolver

namespace NextPDF\Core\Typography;

final class BiDiResolver

/**
 * 解析文字的 BiDi 邏輯順序（Unicode UAX #9）。
 *
 * @param non-empty-string $text     原始文字（可能包含混合方向）
 * @param 'ltr'|'rtl'|'auto' $baseDirection 段落基礎方向
 * @return BiDiRun[]  按視覺順序排列的文字片段
 */
public function resolve(string $text, string $baseDirection = 'auto'): array

/**
 * 偵測文字的主要方向。
 *
 * @return 'ltr'|'rtl'
 */
public function detectDirection(string $text): string

BiDiRun

final readonly class BiDiRun
{
    public string         $text;
    public 'ltr'|'rtl'   $direction;
    public int            $level;     // BiDi 層級（0-125）
    public int            $startOffset;  // 在原始字串的起始位置
}

ArabicShaper

namespace NextPDF\Core\Typography;

final class ArabicShaper

/**
 * 對阿拉伯文進行字型塑形。
 * 回傳塑形後的字型字符序列（已選擇正確的字母形式）。
 *
 * @param non-empty-string $text     阿拉伯文原始文字（Unicode）
 * @param RegisteredFont   $font     目標字型（必須含 Arabic 字形）
 * @return list<ShapedGlyph>
 */
public function shape(string $text, RegisteredFont $font): array

延伸閱讀