本文详解如何在 Django 项目中利用 pdfkit 将多个 HTML 内容块分别渲染为独立 PDF 页面，核心是通过 CSS 的 page-break-after: always 实现精准分页。
本文详解如何在 django 项目中利用 pdfkit 将多个 html 内容块分别渲染为独立 pdf 页面，核心是通过 css 的 `page-break-after: always` 实现精准分页。
在使用 pdfkit（基于 wkhtmltopdf 的 Python 封装）将 HTML 转换为 PDF 时，若需将多个逻辑内容单元（如报告章节、练习题、示例模块）严格分隔为独立页面，仅拼接 HTML 字符串是不够的——默认情况下所有内容会连续排版，可能跨页或挤在同一页面。真正的解决方案在于控制 PDF 分页行为的 CSS 分页属性。
pdfkit 完全支持标准 CSS 分页规则（需 wkhtmltopdf ≥ 0.12.0），其中最常用且可靠的是：
<div style="page-break-after: always;"></div>
该样式会强制浏览器（及 wkhtmltopdf 渲染引擎）在此元素后插入分页符，确保后续内容始终从新一页开始。
以下是在 Django 项目中的完整实践示例（适配您的原始代码）：
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
立即学习“Python免费学习笔记（深入）”；
import pdfkit
from django.template.loader import render_to_string
my_contents = [
{'title': 'Example 1', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 2', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 3', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 4', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
{'title': 'Example 5', 'contents': ['Lorem ipsum dolor', 'Lorem ipsum']},
]
final_html = ''
for i, content in enumerate(my_contents):
data = {
'title': content['title'],
'contents': content['contents'],
}
# 渲染每个模块的 HTML 模板
final_html += render_to_string('pdfs/routines_handout.html', data)
# 在除最后一个模块外的所有模块末尾添加分页符
if i < len(my_contents) - 1:
final_html += '<div style="page-break-after: always;"></div>'
# 生成 PDF（注意：确保 wkhtmltopdf 已正确安装并可被 pdfkit 找到）
pdfkit.from_string(final_html, 'out.pdf')✅ 关键注意事项：
-
不要在末尾添加多余分页符：如示例所示，仅在前 N−1 个模块后插入 ，否则 PDF 末尾会出现空白页；
- CSS 作用域安全：page-break-after 是内联样式，无需额外 CSS 文件，兼容性高；
- 替代方案（推荐进阶使用）：也可在模板中直接定义分页规则，例如在 routines_handout.html 底部添加：
{% if not forloop.last %}<div style="page-break-after: always;"></div>{% endif %}这样逻辑更清晰，避免 Python 层拼接 HTML 的脆弱性；
- wkhtmltopdf 配置建议：如遇分页失效，检查是否启用了 --enable-local-file-access（尤其当模板含本地静态资源时），或尝试添加 --page-size A4 --margin-top 20 --margin-bottom 20 等参数提升排版稳定性。
总结：page-break-after: always 是 pdfkit 多页生成中最轻量、最可靠的分页手段。结合 Django 模板系统，可灵活构建结构化、可维护的 PDF 报告流水线——无需复杂布局引擎，一行 CSS 即可掌控每一页的边界。
