跳轉到

文字形塑

複雜文字佈局（Complex Text Layout，CTL）是支援阿拉伯文、希伯來文、印度文字系統等語言的關鍵技術。NextPDF 內建 BiDiResolver 與 ArabicShaper，在不依賴外部 ICU 函式庫的前提下處理雙向文字與字形連接。

雙向文字（BiDi）

根據 Unicode 雙向演算法（UBA，Unicode Standard Annex #9），混合左至右（LTR）與右至左（RTL）的文字需要重新排列：

use NextPDF\Typography\Bidi\BiDiResolver;

// BiDiResolver 由 TextRenderer 內部自動調用
// 混合方向文字示例
$document->text()->write(
    text: 'Hello مرحبا World',  // 英文-阿拉伯文-英文
    position: Position::at(x: 20.0, y: 50.0),
    style: FontStyle::create(fontFamily: 'NotoSansArabic-Regular'),
    baseDirection: TextDirection::LeftToRight,
);

BiDi 段落方向

use NextPDF\Typography\Bidi\TextDirection;

// 明確指定段落方向（建議始終明確指定）
$document->text()->write(
    text: 'مرحباً بكم في NextPDF',  // 純阿拉伯文
    position: Position::at(x: 170.0, y: 50.0), // 注意：RTL 段落通常從右邊對齊
    baseDirection: TextDirection::RightToLeft,
);

ArabicShaper

阿拉伯文字母根據在單詞中的位置（開頭、中間、結尾、獨立）有不同的字形。ArabicShaper 負責選擇正確的字形並處理連字（ligature）：

use NextPDF\Typography\Arabic\ArabicShaper;

// ArabicShaper 由 TextRenderer 內部自動調用
// 字形選擇：阿拉伯字母 ع 在不同位置的字形
// 獨立：ع  開頭：عـ  中間：ـعـ  結尾：ـع

語言特定形塑

文字系統 支援功能
阿拉伯文 字形連接、連字、Kashida、Harakat（母音符號）
希伯來文 BiDi 排列、Cantillation marks（部分）
梵文（Devanagari） 基本合體字（conjuncts）
泰文 基線上下字元定位

數字替換

阿拉伯文文件通常使用阿拉伯-印度數字（٠١٢٣٤٥٦٧٨٩）而非西方阿拉伯數字：

use NextPDF\Typography\Arabic\DigitSubstitution;

$document->text()->write(
    text: '12345',
    position: Position::at(x: 20.0, y: 50.0),
    digitSubstitution: DigitSubstitution::ArabicIndic,  // 輸出：١٢٣٤٥
);

與 Rust Spectrum 的整合

高頻文字形塑場景可啟用 Spectrum 加速器，將形塑工作卸載至 Rust 實作的 HarfBuzz 綁定：

// 在 Process 設定中啟用 Spectrum
$process = Process::create(
    enableSpectrum: true,
    spectrumCapabilities: [SpectrumCapability::TextShaping],
);

參見