多頁文件

當內容無法在單頁內呈現時，就需要建立多頁文件。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');

下一步

• 頁首與頁尾 -- 為多頁文件加入頁首頁尾
• 目錄產生 -- 自動產生目錄
• 浮水印 -- 在所有頁面加入浮水印