模板 (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) 开始。