如何在mPDF中加载页眉页脚不生成空白页，支持动态页面格式？

问题背景 #

需要生成包含以下特性的PDF文件：

• 多页面，每个页面可自定义格式/方向
• 不同页面使用不同的页眉页脚
• 当前实现：循环中通过$pdf->AddPage()动态修改页面属性，页眉页脚定义通过$pdf->writeHTML($defs)加载

核心痛点 #

• 执行$pdf->writeHTML($defs)会直接生成空白页，导致实际内容从第2页开始
• 省略该方法则页眉页脚定义无法被加载，页面无页眉页脚

现有代码片段 #

循环逻辑代码 #

foreach ($group->getPages() as $page) {
    $defs = '';
    $defs .= $page->getHeader();
    $defs .= $page->getFooter();     

    $pdf->writeHTML($defs);

    // 添加页面
    $pdf->AddPage(
        orientation: $page->getOrientation()?->getTcpdfCode() ?? 'P',
        newformat: $page->getFormat()?->getTcpdfCode() ?? 'A4'
    );

    // 写入内容
    $html = $page->getContent(); // 原代码缺少分号，已修正
    $pdf->writeHTML($html);
}

页眉定义代码 #

<style>
    @page :first {
        header: headerFirstPage;
        margin-top: 30mm;
    }

    @page {
        header: headerOtherPage;
        margin-top: 10mm;
    }
</style>
<htmlpageheader name="headerFirstPage" style="display:none">
    <img src="" style="margin: 30px 0 0 10px; width: 350px;" />
    <img src="" style="float: right; width: 280px;" />
</htmlpageheader>
<htmlpageheader name="headerOtherPage" style="display:none">
    <img src="" style="float: right; width: 280px;" />
</htmlpageheader>

页脚定义代码 #

<style>
    @page {
        footer: footer;
        margin-bottom: 20mm;
    }
</style>

<htmlpagefooter name="footer" style="display:none">
    <div style="width: 100%; margin: 0;">
        <div style="margin-top: -13px; padding: 0 10px 10px 0; text-align: right;">
            <p style="margin: 0; padding: 0; font-style: italic; font-size: 11px; line-height: 1;">{{ document.title }} - Page {PAGENO}/{nbpg}</p>
        </div>
    </div>
</htmlpagefooter>

解决方案 #

方案1：循环内加载定义时避免生成页面 #

通过临时关闭页眉页脚打印，并调整writeHTML的参数，实现只加载定义而不生成空白页：

foreach ($group->getPages() as $page) {
    $defs = '';
    $defs .= $page->getHeader();
    $defs .= $page->getFooter();

    // 临时关闭页眉页脚打印，防止加载定义时渲染内容
    $pdf->setPrintHeader(false);
    $pdf->setPrintFooter(false);
    
    // 加载HTML定义：$ln=0（不自动换行）、$fill=false（不填充背景），避免创建页面
    $pdf->writeHTML($defs, 0, false, false, false);
    
    // 恢复页眉页脚打印
    $pdf->setPrintHeader(true);
    $pdf->setPrintFooter(true);

    // 添加页面，此时已加载对应页眉页脚规则
    $pdf->AddPage(
        orientation: $page->getOrientation()?->getTcpdfCode() ?? 'P',
        newformat: $page->getFormat()?->getTcpdfCode() ?? 'A4'
    );

    // 写入页面内容
    $html = $page->getContent();
    $pdf->writeHTML($html);
}

方案2：预加载所有页眉页脚定义（适用于固定类型场景） #

如果页眉页脚的类型有限（比如仅首页/其他页两种页眉、一种页脚），可以在循环开始前一次性加载所有定义，避免重复加载导致的问题：

// 预加载所有需要的页眉页脚定义
$allDefs = '';
// 替换为实际获取所有页眉页脚定义的逻辑
$allDefs .= $firstPageHeaderHtml;
$allDefs .= $otherPageHeaderHtml;
$allDefs .= $commonFooterHtml;

// 加载定义，不生成页面
$pdf->setPrintHeader(false);
$pdf->setPrintFooter(false);
$pdf->writeHTML($allDefs, 0, false, false, false);
$pdf->setPrintHeader(true);
$pdf->setPrintFooter(true);

// 循环添加页面
foreach ($group->getPages() as $page) {
    $pdf->AddPage(
        orientation: $page->getOrientation()?->getTcpdfCode() ?? 'P',
        newformat: $page->getFormat()?->getTcpdfCode() ?? 'A4'
    );

    $html = $page->getContent();
    $pdf->writeHTML($html);
}

原理说明 #

• TCPDF的<htmlpageheader>/<htmlpagefooter>属于文档级缓存定义，加载后会被保留，无需重复加载
• writeHTML默认会将内容渲染到当前页面，通过$ln=0禁止自动换行，配合临时关闭页眉页脚打印，可仅加载定义而不生成可见内容
• @page选择器会自动匹配后续添加的页面，应用对应的页眉页脚规则

内容的提问来源于stack exchange，提问作者MatDepInfo