back
loading skill details...
HTML 转 PPTX 形状转换器 — 将 HTML 幻灯片转换为完全可编辑的 PPTX,自动内嵌外部 CSS,保留 CSS 样式、布局,映射为 PPTX 原生形状(矩形/文本框/图片等)
---
name: html2pptx-shape
description: HTML 转 PPTX 形状转换器 — 将 HTML 幻灯片转换为完全可编辑的 PPTX,自动内嵌外部 CSS,保留 CSS 样式、布局,映射为 PPTX 原生形状(矩形/文本框/图片等)
metadata:
openclaw:
version: 3.0
requires:
pip:
- python-pptx
- beautifulsoup4
- pillow
- requests
- cssutils
- premailer
- playwright
---
# 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>` | Freeform | SVG 路径转 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']}")
```
---
## 文件结构
```
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`/`::after` | PPTX 不支持伪元素 | 忽略警告 |
| `background-clip: text` | 渐变文字转纯色 | 手动在 PPTX 中添加渐变 |
| 复杂 SVG | 降级为占位符 | 简化 SVG 或转为图片 |
---
## 依赖安装
```bash
# 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 的对比
| 特性 | html2pptx-shape | html-to-pptx |
|------|-----------------|--------------|
| CSS 内嵌 | ✅ 自动 | ⚠️ 需要预处理器 |
| CSS 变量解析 | ✅ 完整支持 | ⚠️ 部分支持 |
| 形状映射 | ✅ 原生 PPTX 形状 | ⚠️ 简化文本框 |
| 可编辑性 | ✅ 完全可编辑 | ✅ 完全可编辑 |
| 文件大小 | 小 (30-50KB) | 小 (30-50KB) |
| 截图高保真 | ❌ | ✅ 支持 |
---
## 更新日志
### v1.0.0 (2026-04-17)
- ✅ 初始版本
- ✅ 自动内嵌外部 CSS
- ✅ CSS 变量完整解析(支持任何选择器)
- ✅ CSS 样式手动内联(使用 cssutils)
- ✅ PPTX 原生形状映射
- ✅ 16:9 标准比例
---
## License
MIT
## Author
老 6 🎯
don't have the plugin yet? install it then click "run inline in claude" again.