布局 (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)