跳转至

HTML 转图片

将本地 HTML 渲染为完整、清晰的 PNG。默认工具链：Python 3 + Playwright (Chromium)。

快速执行

python3 scripts/html_to_image.py /path/to/diagram.html

常用参数：

# 指定输出路径
python3 scripts/html_to_image.py input.html -o output.png

# 高清（2x，默认）
python3 scripts/html_to_image.py input.html --dpr 2

# 超清（3x）
python3 scripts/html_to_image.py input.html --dpr 3 -o diagram@2x.png

依赖（首次使用）：

pip install playwright
playwright install chromium

默认行为

项 默认
输出路径 与 HTML 同目录、同名 .png
设备像素比 2（高清）
捕获范围 header + .legend（图例）+ .wrap（主图）
网络 需要加载 CDN 资源（如 Mermaid）时请求 full_network

用户未指定文件名时，优先输出 {stem}@2x.png；若用户要求覆盖或只要一个文件，用 -o 明确指定。

工作流程

  1. 读最新 HTML：以磁盘上当前文件为准，不缓存旧截图。
  2. 宽视口预渲染：先用 10000×2600 视口加载，避免 Mermaid 宽图被挤窄。
  3. 等待渲染完成：networkidle + 等待 .mermaid svg 出现 + 额外 2–3 秒。
  4. 修复 SVG 裁切（Mermaid 必做）：
  5. 遍历 SVG 内全部图形元素计算真实 bbox
  6. 重设 viewBox，底部额外留白（防止子图底边被裁）
  7. 展开 .wrap 的 overflow: auto
  8. 增强图例（用户要求「有色块说明」时）：
  9. 放大 .legend 字号与色块尺寸
  10. 给图例加浅灰背景框，确保截图可读
  11. 精确测量：按 header、.legend、.wrap 的包围盒计算截图宽高。
  12. 设置视口 = 内容尺寸，用 clip 截图（不用 body.screenshot()，易丢底部）。
  13. 验收：确认关键节点未超出 SVG 底部；不完整则增大 padBottom 后重跑。

常见踩坑

现象 原因 处理
底部子图丢失（如 ershoucheMain / zufangmain 依赖链） Mermaid SVG viewBox 高度不足 脚本内 fullBBox + 加大 padBottom
只截到左侧一部分 视口宽度默认 1280，宽图未展开 先宽视口渲染，再按内容宽度设视口
没有色块图例 只截了 .wrap 捕获范围包含 header + .legend
图片模糊 device_scale_factor 太低 使用 --dpr 2 或 3
右侧大量空白 视口设为 12000 未回收 按实测 totalW 精确设视口

自定义样式注入

脚本通过 INJECT_STYLE 在截图前注入 CSS，默认：

  • 白底、取消滚动裁切
  • 图例加大加框（有 .legend 时）
  • .mermaid svg 取消 max-width 限制

HTML 结构若非 header / .legend / .wrap，用 --selector 指定捕获根节点，或修改脚本中 CAPTURE_SELECTORS。

无 Playwright 时的备选

优先级低于 Playwright，仅在 Chromium 不可装时使用：

  1. 本机 Chrome headless：google-chrome --headless --screenshot --window-size=...
  2. Mermaid CLI：仅当 HTML 可拆出纯 .mmd 源码时

宽版 flowchart + 图例 + 复杂子图，始终优先 Playwright。

验收清单

截图完成后自查：

  • [ ] 标题与色块图例完整可见
  • [ ] 最宽节点无横向裁切
  • [ ] 最底部节点（含 subgraph 边框）无纵向裁切
  • [ ] 文字在 100% 缩放下可读（不够则提高 --dpr）
  • [ ] 文件已保存到用户指定目录

脚本位置

本 skill 自带可执行脚本：scripts/html_to_image.py

Agent 执行时应使用本 skill 目录下的脚本绝对路径，或先将 skill 目录 cd 进去再运行。