PDF 生成技能

目的：从 HTML/CSS 生成专业 PDF，避免空白间隙与布局异常。

问题所在

在基于 HTML 生成 PDF 时，使用 page-break-inside: avoid 会导致孤立空白（orphan whitespace）——即无法完整容纳在当前页的内容会被整体推至下一页，从而在当前页底部留下大片空白。

解决方案

1. 使用流式布局（而非固定页面容器）

❌ 错误做法：

✅ 正确做法：

应改用 @page CSS 规则，而非依赖固定高度的页面容器：

@page {
    size: A4;
    margin: 18mm 15mm;
}

2. 仅对小型元素启用防断行保护

仅对满足以下条件的元素应用 break-inside: avoid：

• 尺寸较小（如卡片、单行、短型盒子）
• 若被分页截断会显得不完整或断裂

✅ 应保护的元素：

• 单个表格行（tr）
• 卡片（高度 < 100px）
• 时间线条目（timeline items）
• 步骤项（step items）
• 高亮框（highlight boxes）

❌ 不应保护的元素：

• 整张表格（entire tables）
• 大型容器（large containers）
• 整节内容（entire sections）
• 多列布局（multi-column layouts）
• 位于文档末尾的引用框（quote boxes at document end）

3. 同时使用现代与兼容性属性

.small-element {
    break-inside: avoid;        /* 现代标准 */
    page-break-inside: avoid;   /* 兼容旧版引擎 */
}

4. 确保标题与后续内容同页

h2, h3, h4, .section-header {
    break-after: avoid;
    page-break-after: avoid;
}

5. 防止孤行（orphan lines）

body {
    orphans: 3;  /* 页面底部至少保留 3 行 */
    widows: 3;   /* 页面顶部至少保留 3 行 */
}

6. 允许表格跨页，但保持行内完整性

table {
    /* 不设置 break-inside: avoid */
}

tr {
    break-inside: avoid;
    page-break-inside: avoid;
}

模板

@page {
    size: A4;
    margin: 18mm 15mm;
}

body {
    font-size: 10pt;
    line-height: 1.5;
    orphans: 3;
    widows: 3;
}

/* 标题与后续内容保持同页 */
h2, h3, h4 {
    break-after: avoid;
    page-break-after: avoid;
}

/* 小型元素禁止分页截断 */
.card, .highlight-box, .step, .timeline-item {
    break-inside: avoid;
    page-break-inside: avoid;
}

/* 表格行保持完整，表格本身可跨页 */
tr {
    break-inside: avoid;
    page-break-inside: avoid;
}

/* 大型容器保持自然流式布局 */
table, .section, .two-col {
    /* 不设置 break-inside: avoid */
}

@media print {
    body { 
        -webkit-print-color-adjust: exact; 
        print-color-adjust: exact; 
    }
}

工具

WeasyPrint 命令示例

weasyprint input.html output.pdf

发布前检查清单

在发送任何 PDF 文件之前，请务必完成以下检查：

• 在 PDF 查看器中打开，逐页滚动检查全部内容
• 检查是否存在大段空白间隙
• 确保页面顶部未出现单行孤立文本（orphan lines）
• 验证表格未在某一行中间发生不自然的分页断裂
• 确认标题下方紧随正文内容，而非单独出现在页面底部

常见错误

参考资料

• WeasyPrint 官方文档：https://doc.courtbouillon.org/weasyprint/
• CSS Paged Media 标准：https://www.w3.org/TR/css-page-3/
• Print CSS 实践指南：https://www.smashingmagazine.com/2018/05/print-stylesheets-in-2018/

本技能由 Bartok 创建 — 2026 年 3 月 6 日