本文详解如何在 go 中借助 go-wkhtmltopdf 实现「每页独立起始」的 pdf 生成——通过 css 分页指令隔离内容、分离头尾模板，并动态注入变量，彻底避免表格跨页断裂与页眉误入前一页等问题。

本文详解如何在 go 中借助 go-wkhtmltopdf 实现「每页独立起始」的 pdf 生成——通过 css 分页指令隔离内容、分离头尾模板，并动态注入变量，彻底避免表格跨页断裂与页眉误入前一页等问题。

在使用 go-wkhtmltopdf 构建动态报表系统时，一个常见痛点是：当 HTML 内容（如长表格）自然流式渲染时，wkhtmltopdf 默认按内容高度自动分页，导致页眉被“挤”到上一页末尾、表格行被强行截断，破坏阅读逻辑和专业排版。解决核心在于将分页控制权从 wkhtmltopdf 的自动布局交还给开发者——即显式声明每页内容边界，并将页眉/页脚完全解耦为独立模板。

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

✅ 正确实践：三步实现精准分页

1. HTML 内容层：用 page-break-before: always 显式分页
   为每个逻辑页面（如含 20 行数据的表格块）包裹一个带 .page 类的 <div>，并在 CSS 中强制其始终在新页开始：

   <style>
     .page {
       page-break-before: always; /* 关键：确保新页开始 */
       break-before: page;         /* 推荐同时添加现代标准语法 */
       font-size: 16px;
       margin: 0;
     }
     /* 避免内部元素意外分页 */
     .page table, .page tr, .page td {
       page-break-inside: avoid;
     }
   </style>
   <body>
     <div class="page">
       <h2>第 1 页报告</h2>
       <table>...</table>
     </div>
     <div class="page">
       <h2>第 2 页报告</h2>
       <table>...</table>
     </div>
   </body>

2. PDF 生成层：禁用内容内嵌头尾，改用 Header* / Footer* 属性注入
   ❌ 错误做法：在 HTML 中硬编码 <header> 或 <footer> 标签 → 容易被 page-break 拉扯变形。
   ✅ 正确做法：通过 Page 对象的专用方法设置头尾，由 wkhtmltopdf 在每页渲染时独立插入：

   page := wkhtml.NewPageReader(strings.NewReader(html))
   
   // ✅ 使用内置页眉：支持 [page], [frompage], [topage] 等占位符
   page.HeaderCenter.Set("报表 - 第 [page] 页")
   page.HeaderLine.Set(true) // 显示分隔线
   
   // ✅ 使用自定义 HTML 页脚（推荐用于复杂布局）
   page.FooterHTML.Set("./footer.html")
   
   // ✅ 动态传参：供 footer.html 中 JavaScript 解析
   page.Replace.Set("report_id", "RPT-2024-001")
   page.Replace.Set("generated_at", time.Now().Format("2006-01-02 15:04"))

3. 页脚模板（footer.html）：安全解析并渲染动态内容
   wkhtmltopdf 会将 Replace 参数以 URL 查询字符串形式注入页脚 HTML。以下是一个健壮的 footer.html 示例，兼容所有常用变量：

   <!DOCTYPE html>
   <html>
   <head>
     <script>
       function subst() {
         const params = new URLSearchParams(window.location.search);
         const vars = Object.fromEntries(params.entries());
         const classes = ['page', 'frompage', 'topage', 'date', 'time', 'report_id', 'generated_at'];
         classes.forEach(cls => {
           document.querySelectorAll('.' + cls).forEach(el => {
             el.textContent = vars[cls] || '';
           });
         });
       }
     </script>
   </head>
   <body style="margin: 0; padding: 0;" onload="subst()">
     <table width="100%" style="border-top: 1px solid #ccc; font-size: 12px;">
       <tr>
         <td align="left" class="report_id"></td>
         <td align="center">生成时间：<span class="generated_at"></span></td>
         <td align="right">第 <span class="page"></span> 页 / 共 <span class="topage"></span> 页</td>
       </tr>
     </table>
   </body>
   </html>

⚠️ 关键注意事项

• CSS 分页属性兼容性：page-break-before 是广泛支持的旧标准，但建议同时添加 break-before: page（CSS Fragmentation Module Level 3），提升未来兼容性。
• 页边距必须显式设置：若未调用 pdfg.MarginTop.Set() 或 pdfg.MarginBottom.Set()，页眉/页脚可能被裁切。建议预留 ≥10mm 安全边距。
• 页脚 HTML 路径需为绝对路径或工作目录相对路径：FooterHTML.Set() 不支持嵌入式 HTML 字符串，必须指向磁盘文件。
• 动态内容防 XSS：footer.html 中的 JavaScript 仅做文本替换，不执行用户输入，但若需渲染富文本，请严格过滤 vars 值。
• 性能优化：对大量分页（如百页报表），避免在单个 HTML 中拼接全部 .page 块；可改为循环创建多个 PageReader 并 AddPage()，内存更可控。

通过以上结构化方案，你不仅能彻底解决“页眉窜页”“表格断行”等排版顽疾，还能灵活扩展页眉徽标、多级页码、章节标题等企业级报表需求。最终生成的 PDF 将严格遵循设计预期：每页以完整页眉启始，以规范页脚收束，内容区块边界清晰、专业可靠。