多页文件

当内容无法在单页内呈现时，就需要创建多页文件。TCPDF-Next 支持手动新增页面、自动分页、混合不同页面尺寸，以及页码管理等功能。

手动新增页面

最基本的做法是通过 addPage() 逐页新增内容：

<?php

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Content\FontStyle;

$pdf = PdfDocument::create()
    ->setTitle('多页文件示例')
    ->setPageFormat(PageFormat::A4)
    ->build();

// 第一页：封面
$page1 = $pdf->addPage();
$page1->addText('年度技术报告')
    ->setPosition(105, 120)
    ->setFont('Helvetica', size: 28, style: FontStyle::BOLD)
    ->setAlignment(Alignment::CENTER);

$page1->addText('技术部门 | 2026 年 2 月')
    ->setPosition(105, 140)
    ->setFont('Helvetica', size: 14)
    ->setAlignment(Alignment::CENTER);

// 第二页：目录
$page2 = $pdf->addPage();
$page2->addText('目录')
    ->setPosition(20, 25)
    ->setFont('Helvetica', size: 18, style: FontStyle::BOLD);

$page2->addText('1. 项目概述 .......... 3')
    ->setPosition(20, 45)
    ->setFont('Helvetica', size: 11);

$page2->addText('2. 技术架构 .......... 5')
    ->setPosition(20, 55)
    ->setFont('Helvetica', size: 11);

// 第三页：正文
$page3 = $pdf->addPage();
$page3->addText('第一章：项目概述')
    ->setPosition(20, 25)
    ->setFont('Helvetica', size: 18, style: FontStyle::BOLD);

$page3->addParagraph('本章节概述了 2026 年度所有主要技术项目的进展与成果...')
    ->setPosition(20, 45)
    ->setWidth(170)
    ->setFont('Helvetica', size: 11)
    ->setLineHeight(1.5);

$pdf->save('multi_page.pdf');

自动分页

当写入的内容超出页面底部时，TCPDF-Next 可以自动创建新页面并接续内容：

use YeeeFang\TcpdfNext\Html\HtmlRenderer;

$pdf = PdfDocument::create()
    ->setPageFormat(PageFormat::A4)
    ->setAutoPageBreak(true, margin: 25) // 底部保留 25mm 边距
    ->build();

$pdf->addPage();
$renderer = new HtmlRenderer($pdf);

// 写入大量内容，系统自动处理分页
$longContent = str_repeat(
    '<p>这是一段测试文字，用来展示自动分页功能。'
    . 'TCPDF-Next 会在内容即将超出页面时自动换页，开发者不需要手动计算。</p>',
    30
);

$renderer->writeHtml($longContent);

分页事件回调

您可以通过回调函数，在每次自动分页时执行自定义逻辑：

use YeeeFang\TcpdfNext\Graphics\Color;

$pdf->onPageBreak(function (Page $newPage, int $pageNumber) {
    // 在每个新页面顶部画一条分隔线
    $newPage->drawLine(20, 15, 190, 15)
        ->setColor(Color::hex('#3498DB'))
        ->setWidth(0.5);
});

混合页面尺寸与方向

同一份 PDF 中可以混合不同的页面尺寸与方向，适合包含横向图表或大型表格的报告：

// A4 纵向
$pdf->addPage();

// A4 横向（适合宽表格或图表）
$pdf->addPage(PageFormat::A4_LANDSCAPE);

// A3 页面（大尺寸海报或工程图）
$pdf->addPage(PageFormat::A3);

// Letter 尺寸（美规纸张）
$pdf->addPage(PageFormat::LETTER);

页码管理

显示页码

// 在页脚加入页码
$pdf->onPageFooter(function (Page $page, int $pageNumber, int $totalPages) {
    $page->addText("第 {$pageNumber} 页，共 {$totalPages} 页")
        ->setPosition(105, 285)
        ->setFont('Helvetica', size: 9)
        ->setAlignment(Alignment::CENTER);
});

跳过封面页码

如果封面和目录不需要显示页码，可以设置起始页号：

// 封面页（不计入页码）
$pdf->addPage();
// ... 封面内容

// 目录页（不计入页码）
$pdf->addPage();
// ... 目录内容

// 从这里开始计算为第 1 页
$pdf->setStartingPageNumber(1);

$pdf->addPage();
// ... 正文内容

书签导航

为长文件加入书签，让用户能在 PDF 阅读器的导航面板中快速跳转：

$page1 = $pdf->addPage();
$pdf->addBookmark('第一章：简介', level: 0);

$page2 = $pdf->addPage();
$pdf->addBookmark('第二章：核心概念', level: 0);
$pdf->addBookmark('2.1 基础架构', level: 1);
$pdf->addBookmark('2.2 配置选项', level: 1);

$page3 = $pdf->addPage();
$pdf->addBookmark('第三章：实现', level: 0);

完整示例：多章节报告

<?php

require_once __DIR__ . '/vendor/autoload.php';

use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Content\FontStyle;
use YeeeFang\TcpdfNext\Content\Alignment;
use YeeeFang\TcpdfNext\Graphics\Color;

$pdf = PdfDocument::create()
    ->setTitle('2026 年度技术报告')
    ->setAuthor('技术部门')
    ->setPageFormat(PageFormat::A4)
    ->setAutoPageBreak(true, margin: 25)
    ->build();

// 封面
$cover = $pdf->addPage();
$cover->addText('2026 年度技术报告')
    ->setPosition(105, 100)
    ->setFont('Helvetica', size: 28, style: FontStyle::BOLD)
    ->setColor(Color::hex('#2C3E50'))
    ->setAlignment(Alignment::CENTER);

$cover->addText('技术部门 | 2026 年 2 月')
    ->setPosition(105, 120)
    ->setFont('Helvetica', size: 14)
    ->setColor(Color::hex('#7F8C8D'))
    ->setAlignment(Alignment::CENTER);

// 章节内容
$chapters = [
    '项目概述' => '本章节概述了年度所有主要技术项目的进展与成果...',
    '技术架构' => '我们在本年度对系统架构进行了重大升级...',
    '性能优化' => '通过一系列优化措施，系统响应时间降低了 60%...',
];

foreach ($chapters as $title => $content) {
    $page = $pdf->addPage();
    $pdf->addBookmark($title, level: 0);

    $page->addText($title)
        ->setPosition(20, 25)
        ->setFont('Helvetica', size: 20, style: FontStyle::BOLD)
        ->setColor(Color::hex('#2C3E50'));

    $page->drawLine(20, 38, 80, 38)
        ->setColor(Color::hex('#3498DB'))
        ->setWidth(0.8);

    $page->addParagraph($content)
        ->setPosition(20, 48)
        ->setWidth(170)
        ->setFont('Helvetica', size: 11)
        ->setLineHeight(1.5)
        ->setAlignment(Alignment::JUSTIFY);
}

$pdf->save('annual_report.pdf');

下一步

• 页眉与页脚 -- 为多页文件加入页眉页脚
• 目录生成 -- 自动生成目录
• 水印 -- 在所有页面加入水印