テンプレート（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) から始まります。