Playwright 默认导出 PDF 时会忽略 CSS 背景色（如 background-color），需显式启用 print_background=True 才能渲染背景样式。本文详解配置方法、代码示例及关键注意事项。
playwright 默认导出 pdf 时会忽略 css 背景色（如 `background-color`），需显式启用 `print_background=true` 才能渲染背景样式。本文详解配置方法、代码示例及关键注意事项。
在使用 Playwright 的 pdf() 方法生成 PDF 时，一个常见却易被忽视的问题是：即使 HTML 中已正确定义了 background-color（例如 .footer { background-color: red; }），导出的 PDF 仍显示为透明或白色背景。这是因为 Chromium（Playwright 底层浏览器）在 PDF 打印模式下默认禁用背景图形渲染，以提升性能并符合部分打印标准。
✅ 正确解决方案非常简洁：在调用 page.pdf() 时，必须传入参数 print_background=True。该参数等效于 Chrome DevTools 中“更多设置 → 勾选‘背景图形’”的操作，强制浏览器将 CSS 背景颜色、背景图片等一并输出到 PDF。
以下是修正后的完整代码示例（含关键注释）：
from playwright.sync_api import sync_playwright
from string import Template
# 构建带背景色的页脚模板（注意：CSS 中 background-color 已正确定义）
footer_template = """
<style>
.footer {
font-size: 10px;
text-align: center;
width: 100%;
margin: 10px 1cm 0 1cm;
font-family: "Times New Roman", sans-serif;
background-color: #ff6b6b; /* 红色背景，现可正常显示 */
padding: 8px 0; /* 推荐添加内边距，避免内容紧贴边缘 */
color: white; /* 可选：提升文字可读性 */
}
.footer-content {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
height: 100%;
}
.fw-bold {
font-weight: bold;
}
</style>
<div class="footer">
<div class="footer-content">
<p class="fw-bold">Powered By TECHstile.in</p>
<p>This is a Computer Generated Invoice</p>
<p>{{invoice_number}}-
<strong><span class="pageNumber"></span>/<span class="totalPages"></span></strong>
</p>
</div>
</div>
"""
# 渲染模板（假设 invoice_number 已定义）
html_content = Template(footer_template).substitute(invoice_number="INV-2024-001")
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page()
# 设置页面内容（确保 wait_until 覆盖样式加载）
page.set_content(html_content, wait_until="networkidle")
# ✅ 关键一步：必须设置 print_background=True
page.pdf(
path="output_with_background.pdf",
format="A4",
print_background=True, # ← 缺少此行是背景不显示的根本原因
margin={"top": 0, "bottom": 20} # 可选：为页脚预留空间
)
browser.close()⚠️ 注意事项与最佳实践：
-
print_background=True仅对page.pdf()生效，不影响page.screenshot()或其他操作； - 若使用
@page规则或 CSS 打印媒体查询（@media print），请确保background-color未被意外覆盖或设为transparent； - 对于深色背景（如
#000或#333），建议同步设置color和font-weight保证文字清晰可读； - 在
set_content()后，可通过page.evaluate("getComputedStyle(document.querySelector('.footer')).backgroundColor")调试确认样式是否真实应用； - 如需全局启用（如所有页面元素背景），可统一在
或上设置background-color，同样依赖print_background=True。
总结：Playwright PDF 导出背景色失效并非 CSS 语法问题，而是 Chromium 的默认安全/性能策略。只需一行 print_background=True，即可安全、可靠地还原设计稿中的背景视觉效果——这是生成专业发票、报告等正式文档不可或缺的关键配置。
