HTML to PDF
Overview
将HTML文件（本地文件或HTTP URL）转换为高质量PDF，使用Playwright无头Chromium渲染引擎，完整保留CSS渐变、Grid/Flex布局、背景色、字体等样式。适用于包含复杂样式的HTML报告、海报、数据可视化页面等场景。
Prerequisites
运行此技能需要：
- Python 3.8+
- Playwright + Chromium
如未安装，先执行：
pip install playwright
python3 -m playwright install chromium
CLI 参数
python3 scripts/html2pdf.py <source> [output] [options]
| 参数 | 说明 |
|---|---|
source |
HTML文件路径或HTTP/HTTPS URL（必填） |
output |
输出PDF路径（可选，默认与HTML同名.pdf） |
--width |
页面宽度（如 210mm、1200px） |
--height |
页面高度（如 297mm、1697px） |
--format |
标准纸张：A4（默认）、A3、Letter 等 |
--landscape |
横向模式（A4横向 = 297×210mm） |
页面尺寸优先级：--width/--height > --landscape > --format
Workflow
Step 1: 确认输入
确认用户提供的HTML文件路径或URL：
- 本地文件：使用文件路径（如 /path/to/report.html 或 report.html）
- URL：完整的HTTP/HTTPS地址（如 https://example.com/page.html）
Step 2: 选择页面尺寸
根据HTML设计宽度选择合适的PDF页面尺寸：
| 场景 | 参数 | 说明 |
|---|---|---|
| 标准报告/A4纵向 | （默认） | A4 210×297mm |
| 宽屏报告/A4横向 | --landscape |
A4 横向，适合宽屏HTML |
| 与HTML设计宽完全匹配 | --width 1200px --height 1697px |
自定义尺寸，1:1无缩放 |
| 其他标准纸张 | --format A3 |
支持 A3/A2/Letter 等 |
Step 3: 执行转换
# 基本用法（A4纵向）
python3 scripts/html2pdf.py report.html
# 指定输出路径
python3 scripts/html2pdf.py report.html ./output.pdf
# A4 横向（适合宽屏报告）
python3 scripts/html2pdf.py report.html --landscape
# 自定义页面尺寸（与HTML设计宽完全匹配）
python3 scripts/html2pdf.py report.html --width 1200px --height 1697px
# 其他标准纸张
python3 scripts/html2pdf.py report.html --format A3
Step 4: 验证并交付
- 确认PDF文件已生成（检查文件大小 > 0）
- 使用
deliver_attachments工具交付PDF给用户 - 在回复中说明文件名、大小、保存位置
PDF参数
默认配置：
- 纸张格式：A4（可通过 --format / --landscape / --width+--height 修改）
- 边距：上15mm / 下15mm / 左10mm / 右10mm
- 打印背景：是（完整保留CSS背景色、渐变）
- 页眉页脚：关闭
排版一致性建议
为确保PDF与HTML排版完全一致：
1. 使用自定义尺寸：--width 1200px --height 1697px（匹配HTML设计宽度）
2. 或在HTML中添加打印CSS：
css
@page { size: 1200px 1697px; margin: 0; }
@media print {
body { margin: 0; -webkit-print-color-adjust: exact; }
.card { break-inside: avoid; }
}
3. A4横向：--landscape 适合大多数宽屏报告
Troubleshooting
| 问题 | 原因 | 解决方案 |
|---|---|---|
报错 playwright 未找到 |
Python环境未安装playwright | 运行 pip install playwright && python3 -m playwright install chromium |
| PDF内容不全 | 页面JS未加载完成 | 增大 wait_for_timeout 的等待时间（默认5秒） |
| 中文字体缺失 | 系统未安装中文字体 | HTML中使用系统字体栈（PingFang SC / Microsoft YaHei） |
| 文件路径含中文报错 | 路径编码问题 | 使用绝对路径，确保路径格式正确 |
| PDF排版与HTML不一致 | 页面尺寸不匹配 | 使用 --width/--height 指定与HTML设计宽一致的尺寸 |
