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: 验证并交付

1. 确认PDF文件已生成（检查文件大小 > 0）
2. 使用 deliver_attachments 工具交付PDF给用户
3. 在回复中说明文件名、大小、保存位置

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; }

}

```

1. 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设计宽一致的尺寸 |