版面配置 (HasLayout)

HasLayout trait 與 Layout 模組提供頁面層級的結構控制：頁首、頁尾、多欄排版及小冊子模式。此模組由 PageManager、ColumnManager、BookletManager 與 HeaderFooterManager 組成。

所有方法都回傳 static，因此每個呼叫都可以鏈式串接。

頁首與頁尾

內建頁首

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setHeaderData('logo.png', 30, 'Company Name', 'Generated report — Confidential')
    ->setHeaderMargin(10)
    ->setFooterMargin(10)
    ->addPage();

setHeaderData() 接受 logo 路徑、logo 寬度、標題字串與說明字串。

自訂回呼

如果需要完全控制頁首頁尾的內容，可以註冊回呼函式，它會接收 Document 實例作為參數：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

$pdf->setHeaderCallback(function (Document $doc) {
    $doc->setFont('Helvetica', 'B', 12)
        ->cell(0, 10, 'My Company — Confidential', align: 'C', newLine: true)
        ->line(10, 18, 200, 18);
});

$pdf->setFooterCallback(function (Document $doc) {
    $doc->setY(-15)
        ->setFont('Helvetica', '', 8)
        ->cell(0, 10, 'Page ' . $doc->getPage() . '/' . $doc->getNumPages(), align: 'C');
});

$pdf->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Content with custom header and footer');

回呼函式會在每次新增頁面時自動執行。你可以在回呼中使用 getPage() 取得目前頁碼、getNumPages() 取得總頁數，藉此實現「第 X / Y 頁」的頁碼格式。

條件式頁首頁尾

根據頁碼或其他條件，動態調整頁首頁尾的內容：

$pdf->setHeaderCallback(function (Document $doc) {
    $page = $doc->getPage();

    // 第一頁（封面）不顯示頁首
    if ($page === 1) {
        return;
    }

    // 奇偶頁使用不同的頁首配置
    if ($page % 2 === 0) {
        // 偶數頁：章節標題靠左
        $doc->setFont('Helvetica', 'I', 9)
            ->text(15, 10, '第二章 — 系統架構');
    } else {
        // 奇數頁：文件名稱靠右
        $doc->setFont('Helvetica', 'I', 9)
            ->text(160, 10, '技術白皮書');
    }
});

啟用與停用

$pdf->setPrintHeader(false);  // 不渲染頁首
$pdf->setPrintFooter(false);  // 不渲染頁尾

你可以在呼叫 addPage() 之前切換這些設定，以控制特定頁面是否顯示頁首頁尾。例如，封面頁通常不需要頁首頁尾：

$pdf->setPrintHeader(false)
    ->setPrintFooter(false)
    ->addPage()
    ->setFont('Helvetica', 'B', 24)
    ->cell(0, 100, '封面標題', align: 'C')

    // 後續頁面恢復頁首頁尾
    ->setPrintHeader(true)
    ->setPrintFooter(true)
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, '正文內容開始...');

頁首頁尾邊距

$pdf->setHeaderMargin(float $margin);  // 頁面邊緣到頁首的間距
$pdf->setFooterMargin(float $margin);  // 頁面邊緣到頁尾的間距

這些邊距定義了頁面邊緣與頁首/頁尾內容之間的間隔。

多欄排版

定義欄位

$pdf = Document::create()
    ->addPage()
    ->setColumnsArray([
        ['w' => 90, 's' => 5],  // 第 1 欄：寬 90mm，間距 5mm
        ['w' => 90, 's' => 0],  // 第 2 欄：寬 90mm
    ])
    ->setColumn(0)
    ->setFont('Helvetica', '', 10)
    ->multiCell(0, 5, '左欄內容...')
    ->setColumn(1)
    ->multiCell(0, 5, '右欄內容...');

每個項目以 w（寬度）和 s（間距）定義一個欄位。使用 setColumn() 在欄位之間切換。

三欄排版

$pdf->addPage()
    ->setColumnsArray([
        ['w' => 58, 's' => 4],
        ['w' => 58, 's' => 4],
        ['w' => 58, 's' => 0],
    ]);

// 寫入第一欄
$pdf->setColumn(0)
    ->multiCell(0, 5, $column1Text);

// 寫入第二欄
$pdf->setColumn(1)
    ->multiCell(0, 5, $column2Text);

// 寫入第三欄
$pdf->setColumn(2)
    ->multiCell(0, 5, $column3Text);

欄位方法

$pdf->setColumnsArray(array $columns);  // 定義欄位結構
$pdf->setColumn(int $col);              // 切換到指定欄位（從 0 開始）
$col = $pdf->getColumn();               // 取得目前的欄位索引

文字自動流動

當使用 multiCell() 撰寫長篇文字時，內容會在欄位底部自動流動到下一欄。如果最後一欄也滿了，則會自動建立新頁面並從第一欄繼續。

小冊子模式

小冊子模式會交替使用內側與外側邊距，使頁面在列印後可以對折裝訂：

$pdf->setBooklet(bool $val, float $inner, float $outer);

參數	說明
$val	true 啟用、false 停用
$inner	內側（裝訂側）邊距，單位 mm
$outer	外側（邊緣側）邊距，單位 mm

$pdf = Document::create()
    ->setBooklet(true, 20, 10)
    ->addPage()   // 奇數頁：內側邊距在左邊
    ->cell(0, 10, 'Page 1 — wider left margin for binding')
    ->addPage()   // 偶數頁：內側邊距在右邊
    ->cell(0, 10, 'Page 2 — wider right margin for binding');

邊距的交替會在每次呼叫 addPage() 時自動進行。這種設計讓你無需手動計算邊距，只要正常撰寫內容即可。

裝訂側邊距示意

奇數頁（右頁）           偶數頁（左頁）
┌──────────────┐        ┌──────────────┐
│裝│            │        │            │裝│
│訂│   內容區   │        │   內容區   │訂│
│側│            │        │            │側│
│20│            │10      10│            │20│
│mm│            │mm      mm│            │mm│
└──────────────┘        └──────────────┘

分隔線

在頁面中繪製水平分隔線，常用於區分頁首、正文與頁尾：

$pdf->addPage()
    ->setDrawColor(200, 200, 200)
    ->line(15, 20, 195, 20)     // 頁首下方的分隔線
    ->setFont('Helvetica', '', 12)
    ->text(15, 25, '正文內容')
    ->line(15, 277, 195, 277);  // 頁尾上方的分隔線

版面工具選用指南

需求	解決方案
每頁一致的品牌識別	setHeaderData() 或 setHeaderCallback()
頁尾顯示頁碼	setFooterCallback() 搭配 getPage() / getNumPages()
報紙式多欄排版	setColumnsArray() + setColumn()
可裝訂的小冊子輸出	setBooklet()
特定頁面移除頁首	在 addPage() 前呼叫 setPrintHeader(false)