html2pptx-shape — HTML 转 PPTX 形状转换器

将 HTML 幻灯片转换为 完全可编辑的 PPTX，核心特性：

• 自动内嵌外部 CSS — 将 <link> 引用的 CSS 文件嵌入到 <style> 标签
• CSS 样式完整保留 — 颜色、字体、渐变、阴影、边框、圆角
• 布局精确还原 — 元素位置、尺寸、层级关系
• PPTX 原生形状映射 — div→矩形，p/h→文本框，img→图片，svg→形状
• 16:9 标准比例 — 宽屏演示文稿 (13.333" × 7.5")

快速开始

安装依赖

cd /Users/panda/.openclaw/workspace/skills/html2pptx-shape
pip3 install -r requirements.txt
playwright install chromium

基本使用

# 转换 HTML 文件（自动内嵌外部 CSS）
python3 index.py <input.html> [output.pptx]

# 示例
python3 index.py examples/demo.html
python3 index.py my-presentation.html my-output.pptx

输出

功能特性

✅ 自动 CSS 内嵌

自动将外部 CSS 文件嵌入到 HTML 的 <style> 标签中：

<!-- 转换前 -->
<link rel="stylesheet" href="styles.css">
<link rel="stylesheet" href="theme.css">

<!-- 转换后 -->
<style>
/* styles.css 内容 */
/* theme.css 内容 */
</style>

支持：

• ✅ 多个 <link> 标签
• ✅ 相对路径 CSS 文件
• ✅ CSS 变量（:root 和任何选择器中的定义）
• ⚠️ 自动跳过远程 CSS（http/https 开头）

✅ CSS 样式支持

✅ 元素映射

技术实现

1. CSS 嵌入 — 自动将外部 CSS 文件嵌入到 HTML <style> 标签
2. CSS 变量解析 — 收集所有 CSS 变量定义（支持任何选择器）
3. CSS 内联 — 使用 cssutils 解析并应用样式到每个元素
4. HTML 解析 — BeautifulSoup4 解析 DOM 结构
5. 布局计算 — 遍历 DOM 树，计算每个元素的绝对位置
6. 形状创建 — python-pptx 创建对应形状
7. 样式应用 — 将 CSS 属性映射到 PPTX 形状属性
8. 分页处理 — 遍历 section.slide，每页创建一张幻灯片

使用场景

• 将 html-ppt 生成的 HTML 演示文稿转为可编辑 PPTX
• 网页内容存档为 PPTX 格式
• 需要后期编辑的 HTML→PPTX 转换
• 自包含 HTML 文件（无外部依赖）的 PPTX 转换

示例

示例 1：转换 html-ppt 生成的 HTML

python3 index.py examples/demo.html
# 输出：examples/demo_converted.pptx

示例 2：转换带有外部 CSS 的 HTML

python3 index.py my-presentation.html
# 自动嵌入 style.css, theme.css 等外部文件
# 输出：my-presentation_converted.pptx

示例 3：指定输出文件名

python3 index.py input.html output.pptx

示例 4：在 Python 中调用

from index import run
result = run(["./examples/demo.html"])
print(f"Generated: {result['output_file']}")
print(f"Slides: {result['slides_count']}")

文件结构

html2pptx-shape/
├── SKILL.md                 (本文档)
├── README.md                (快速入门)
├── index.py                 (核心转换逻辑)
├── requirements.txt         (Python 依赖)
├── scripts/
│   ├── embed-css.py         (独立 CSS 嵌入工具)
│   ├── debug-convert.py     (调试脚本)
│   ├── check-inline.py      (样式检查脚本)
│   └── debug-vars.py        (变量调试脚本)
└── examples/
    ├── demo.html            (示例 HTML - 4 页)
    ├── demo_converted.pptx  (生成的 PPTX)
    ├── external-css.html    (外部 CSS 测试)
    ├── external-css_converted.pptx
    ├── styles.css
    └── theme.css

完整工作流

从 html-ppt 到 PPTX

# 1. 用 html-ppt 生成 HTML 演示文稿
# (使用 html-ppt skill 创建 HTML)

# 2. 转换为可编辑 PPTX
python3 index.py my-deck/index.html

# 3. 在 PowerPoint 中打开并编辑
open my-deck/index_converted.pptx

处理外部 CSS

# 情况 A: HTML 引用外部 CSS
# index.html 中有：<link rel="stylesheet" href="style.css">

# 直接转换，自动嵌入 CSS
python3 index.py index.html

# 情况 B: 想先内嵌 CSS 再转换
python3 scripts/embed-css.py index.html
python3 index.py index_embedded.html

限制与已知问题

依赖安装

# Python 依赖
pip3 install python-pptx beautifulsoup4 pillow requests cssutils premailer

# Playwright 浏览器（用于截图功能）
playwright install chromium

故障排除

问题：CSS 文件未找到

⚠️  CSS file not found: xxx.css

原因： 相对路径无法解析

解决：

1. 将 CSS 文件移动到正确位置
2. 或使用 scripts/embed-css.py 先内嵌 CSS
3. 或直接将 CSS 内容复制到 <style> 标签中

问题：样式未应用

原因： CSS 选择器太复杂或使用了不支持的属性

解决：

1. 检查 HTML 元素的 class 是否正确
2. 使用内联样式 style="..." 替代
3. 查看转换日志中的 selector error 警告

问题：布局错乱

原因： CSS Grid/Flex 布局被简化

解决：

1. 使用绝对定位 position: absolute 替代
2. 或在 PPTX 中手动调整位置

与 html-to-pptx 的对比

更新日志

v1.0.0 (2026-04-17)

• ✅ 初始版本
• ✅ 自动内嵌外部 CSS
• ✅ CSS 变量完整解析（支持任何选择器）
• ✅ CSS 样式手动内联（使用 cssutils）
• ✅ PPTX 原生形状映射
• ✅ 16:9 标准比例

License

MIT

Author

老 6 🎯