模板 (XObjects)

PDF Form XObjects — 在 TCPDF-Next 中稱為模板 — 可讓你將一段內容錄製一次，然後蓋印到任意數量的頁面上。這非常適合頁首、頁尾、浮水印、商標圖示，以及任何需要在整份文件中重複出現的元素。

所有方法皆回傳 static，因此可以鏈式串接（startTemplate() 除外，它回傳模板 ID）。

快速參考

方法	用途
startTemplate()	開始錄製模板；回傳模板 ID
endTemplate()	停止錄製
printTemplate()	將已錄製的模板放置到目前頁面

基本範例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

// 建立可重複使用的頁首模板
$tpl = $pdf->startTemplate(190, 20);
$pdf->setFont('Helvetica', 'B', 14)
    ->setTextColor(255, 102, 0)
    ->cell(0, 10, 'ACME Corp — Confidential', align: 'C')
    ->line(0, 18, 190, 18);
$pdf->endTemplate();

// 在多個頁面上使用此模板
$pdf->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setFont('Helvetica', '', 12)
    ->setY(35)
    ->cell(0, 10, 'Page 1 content', newLine: true)

    ->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setY(35)
    ->cell(0, 10, 'Page 2 content', newLine: true);

startTemplate()

$tpl = $pdf->startTemplate(float $w = 0, float $h = 0): int

開始錄製新模板。此呼叫之後的所有繪圖操作都會被擷取到模板中，而不是直接渲染到頁面上。

參數	型別	說明
$w	float	模板寬度（使用者單位，0 = 頁面寬度）
$h	float	模板高度（使用者單位，0 = 頁面高度）

回傳一個整數模板 ID，用於後續引用該模板。

WARNING

錄製模板期間請勿呼叫 addPage()。模板是在固定邊界框內擷取內容，並非頁面。

endTemplate()

停止錄製並完成模板。此呼叫之後繪製的內容會再次寫入目前頁面。

printTemplate()

$pdf->printTemplate(int $id, float $x, float $y, float $w = 0, float $h = 0): static

將先前錄製的模板蓋印到目前頁面的指定位置。

參數	型別	說明
$id	int	startTemplate() 回傳的模板 ID
$x	float	頁面上的 X 位置
$y	float	頁面上的 Y 位置
$w	float	顯示寬度（0 = 原始模板寬度）
$h	float	顯示高度（0 = 原始模板高度）

透過改變 $w 和 $h，可以將同一模板以不同大小列印。模板內容會自動縮放以符合。

使用情境

重複的頁首 / 頁尾

$header = $pdf->startTemplate(190, 15);
$pdf->setFont('Helvetica', 'B', 10)
    ->cell(95, 10, 'Company Name', align: 'L')
    ->cell(95, 10, date('Y-m-d'), align: 'R');
$pdf->endTemplate();

for ($i = 1; $i <= 5; $i++) {
    $pdf->addPage()
        ->printTemplate($header, 10, 10)
        ->setY(30)
        ->cell(0, 10, "Content for page {$i}", newLine: true);
}

縮放商標

以不同大小列印同一模板：

$logo = $pdf->startTemplate(60, 20);
$pdf->image('/path/to/logo.png', 0, 0, 60, 20);
$pdf->endTemplate();

$pdf->addPage()
    ->printTemplate($logo, 10, 10, 60, 20)   // 原始大小
    ->printTemplate($logo, 10, 40, 30, 10);   // 縮小一半

提示

• 模板以 PDF Form XObjects 儲存 — 無論列印幾次，內容只定義一次，有效控制檔案大小。
• 模板可以包含任何可繪製的內容：文字、圖片、形狀，甚至其他模板。
• 模板內部的座標系統從邊界框的左上角 (0, 0) 開始。