排版 (HasTypography)

HasTypography trait 控制文字的視覺呈現：字型家族、樣式、大小、間距、伸縮、色彩、陰影與渲染模式。所有方法皆回傳 static，支援鏈式 API 串接。

設定字型

setFont()

以單一呼叫設定目前的字型家族、樣式與大小。

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Normal text', newLine: true)
    ->setFont('Helvetica', 'B', 14)
    ->cell(0, 10, 'Bold text', newLine: true)
    ->setFont('Helvetica', 'BI', 16)
    ->cell(0, 10, 'Bold Italic text', newLine: true);

字型樣式

組合樣式字元可同時套用多種效果：

代碼	樣式
''	一般（Regular）
'B'	粗體（Bold）
'I'	斜體（Italic）
'BI'	粗斜體（Bold Italic）
'U'	底線（Underline）
'D'	刪除線（Strikethrough）
'O'	上線（Overline）

樣式可自由組合：'BIU' 會產生粗體、斜體加底線的文字。

$pdf->setFont('Helvetica', 'BU', 12)
    ->cell(0, 10, 'Bold + Underline', newLine: true)
    ->setFont('Helvetica', 'ID', 12)
    ->cell(0, 10, 'Italic + Strikethrough', newLine: true)
    ->setFont('Helvetica', 'BO', 12)
    ->cell(0, 10, 'Bold + Overline', newLine: true);

setFontSize()

僅變更字型大小，不切換字型家族或樣式。

$pdf->setFont('Helvetica', 'B', 12)
    ->cell(0, 10, '12pt heading', newLine: true)
    ->setFontSize(10)
    ->cell(0, 10, '10pt body text', newLine: true)
    ->setFontSize(8)
    ->cell(0, 10, '8pt footnote', newLine: true);

間距與伸縮

setFontSpacing()

調整每對字元之間額外插入的空間（以點為單位）。

$pdf->setFont('Helvetica', '', 12)
    ->setFontSpacing(0)
    ->cell(0, 10, 'Normal spacing', newLine: true)
    ->setFontSpacing(1.5)
    ->cell(0, 10, 'Expanded spacing', newLine: true)
    ->setFontSpacing(-0.5)
    ->cell(0, 10, 'Tight spacing', newLine: true)
    ->setFontSpacing(0);

setFontStretching()

對字形套用水平縮放。值為 100 時為正常寬度。

$pdf->setFont('Helvetica', '', 14)
    ->setFontStretching(100)
    ->cell(0, 10, 'Normal width (100%)', newLine: true)
    ->setFontStretching(130)
    ->cell(0, 10, 'Stretched (130%)', newLine: true)
    ->setFontStretching(75)
    ->cell(0, 10, 'Condensed (75%)', newLine: true)
    ->setFontStretching(100);

測量文字

getStringWidth()

回傳以目前字型和大小渲染指定字串所需的寬度（使用者單位）。可在繪製前用於計算版面配置。

$pdf->setFont('Helvetica', '', 12);
$width = $pdf->getStringWidth('Invoice Total: $1,250.00');

// 使用測量寬度來靠右對齊儲存格
$pageWidth = $pdf->getPageWidth();
$rightMargin = $pdf->getRightMargin();
$pdf->setX($pageWidth - $rightMargin - $width)
    ->cell($width, 10, 'Invoice Total: $1,250.00');

文字渲染模式

PDF 定義了 8 種文字渲染模式，透過 TextRenderer 列舉控制。這些模式決定文字是填充、描邊、用作裁切路徑，還是隱藏。

模式	值	效果
Fill	0	一般填充文字（預設）
Stroke	1	僅顯示輪廓
FillStroke	2	填充加輪廓
Invisible	3	隱藏但可選取/可搜尋
FillClip	4	填充後加入裁切路徑
StrokeClip	5	描邊後加入裁切路徑
FillStrokeClip	6	填充加描邊後裁切
Clip	7	僅加入裁切路徑

$pdf->setFont('Helvetica', 'B', 36)
    ->setTextRenderingMode(0)
    ->cell(0, 15, 'Filled text', newLine: true)
    ->setTextRenderingMode(1)
    ->cell(0, 15, 'Outlined text', newLine: true)
    ->setTextRenderingMode(2)
    ->cell(0, 15, 'Fill + Stroke', newLine: true)
    ->setTextRenderingMode(3)
    ->cell(0, 15, 'Invisible (but searchable)', newLine: true)
    ->setTextRenderingMode(0);

Invisible 模式（值為 3）特別適合 OCR 疊加層 — 將辨識出的文字放置於掃描圖片上方，使 PDF 可被搜尋，同時圖片仍然可見。

文字色彩

setTextColor()

使用 RGB 值設定文字色彩。

$pdf->setTextColor(0, 0, 0)          // 黑色
    ->cell(0, 10, 'Black text', newLine: true)
    ->setTextColor(220, 50, 50)       // 紅色
    ->cell(0, 10, 'Red text', newLine: true)
    ->setTextColor(0, 102, 204)       // 藍色
    ->cell(0, 10, 'Blue text', newLine: true)
    ->setTextColor(0, 0, 0);          // 重設為黑色

僅傳入單一參數時，會設定灰階值（0 = 黑色，255 = 白色）。

$pdf->setTextColor(128)
    ->cell(0, 10, 'Gray text', newLine: true);

文字陰影

setTextShadow()

為文字套用陰影效果。陰影以關聯陣列定義。

$pdf->setFont('Helvetica', 'B', 28)
    ->setTextShadow([
        'enabled'    => true,
        'depth_w'    => 0.4,    // 水平偏移（mm）
        'depth_h'    => 0.4,    // 垂直偏移（mm）
        'color'      => [180, 180, 180],
        'opacity'    => 0.5,
        'blend_mode' => 'Normal',
    ])
    ->cell(0, 15, 'Heading with Shadow', newLine: true)
    ->setTextShadow(['enabled' => false]);

完整範例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()

    // 標題 — 大字、粗體、藍色
    ->setFont('Helvetica', 'B', 24)
    ->setTextColor(0, 51, 102)
    ->cell(0, 14, 'Monthly Report', newLine: true)

    // 副標題 — 一般字體、灰色、加大間距
    ->setFont('Helvetica', '', 12)
    ->setTextColor(100, 100, 100)
    ->setFontSpacing(1.0)
    ->cell(0, 10, 'February 2026', newLine: true)
    ->setFontSpacing(0)
    ->ln(5)

    // 內文 — 黑色、一般
    ->setFont('Times', '', 11)
    ->setTextColor(0, 0, 0)
    ->multiCell(0, 6, 'Revenue increased 12% compared to the previous quarter. Operating costs remained stable, and net margin improved by 3 percentage points.')
    ->ln(3)

    // 註腳 — 小字、斜體、灰色
    ->setFont('Times', 'I', 8)
    ->setTextColor(150, 150, 150)
    ->cell(0, 5, '* All figures are unaudited.')

    ->save('report.pdf');