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

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

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

快速开始#

安装依赖#

bash

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

基本使用#

bash

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

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

输出#

项目说明文件名<input>_converted.pptx（默认）或指定名称格式PPTX (Office Open XML)比例16:9 widescreen可编辑性✅ 所有文字/形状可编辑

---

功能特性#

✅ 自动 CSS 内嵌#

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

html

<!-- 转换前 -->
<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 样式支持#

CSS 属性PPTX 映射支持度color文字颜色✅background-color填充颜色✅background (gradient)渐变填充⚠️ 转为纯色font-family字体✅font-size字号✅font-weight字重✅text-align对齐方式✅border边框✅border-radius圆角矩形✅box-shadow阴影✅opacity透明度✅width/height尺寸✅position: absolute绝对定位✅

✅ 元素映射#

HTML 元素PPTX 形状说明<div>Rectangle矩形背景/容器<p>, <h1>- <h6>TextBox文本框，保留字体/颜色/对齐<img>Picture图片，支持 base64/URL/本地文件<svg>FreeformSVG 路径转 PPTX 自由形状（简化）<span>(内联)文本格式化，不创建独立形状<ul>, <ol>TextBox列表文本框，保留项目符号

---

技术实现#

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#

bash

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

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

bash

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

示例 3：指定输出文件名#

bash

python3 index.py input.html output.pptx

示例 4：在 Python 中调用#

python

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

---

文件结构#

text

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#

bash

# 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#

bash

# 情况 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

---

限制与已知问题#

限制说明建议CSS 动画不支持（转换为静态）使用截图版保留视觉效果CSS Grid/Flex简化为绝对定位检查布局是否正确外部字体回退到系统字体确保系统有相应字体::before/ ::afterPPTX 不支持伪元素忽略警告background-clip: text渐变文字转纯色手动在 PPTX 中添加渐变复杂 SVG降级为占位符简化 SVG 或转为图片

---

依赖安装#

bash

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

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

---

故障排除#

问题：CSS 文件未找到#

text

⚠️  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 的对比#

特性html2pptx-shapehtml-to-pptxCSS 内嵌✅ 自动⚠️ 需要预处理器CSS 变量解析✅ 完整支持⚠️ 部分支持形状映射✅ 原生 PPTX 形状⚠️ 简化文本框可编辑性✅ 完全可编辑✅ 完全可编辑文件大小小 (30-50KB)小 (30-50KB)截图高保真❌✅ 支持

---

更新日志#

v1.0.0 (2026-04-17)#

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

---

License#

MIT

Author#

老 6 🎯