feat: initial implementation of html2pptx with OpenSpec documentation
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
This commit is contained in:
247
README.md
Normal file
247
README.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# YAML to PPTX Converter
|
||||
|
||||
将 YAML 格式的演示文稿源文件转换为 PPTX 文件，让 AI 也能轻松生成高质量的演示文稿。
|
||||
|
||||
## 🎯 核心特性
|
||||
|
||||
- **人类和 AI 友好**：使用 YAML 格式，简洁可读，易于生成
|
||||
- **模板系统**：可复用的幻灯片布局，大幅减少重复配置
|
||||
- **核心元素支持**：文本、图片、形状、表格
|
||||
- **精确布局控制**：基于英寸单位的精确定位
|
||||
- **简洁设计**：颜色和样式直接在模板中定义，无需额外配置
|
||||
- **浏览器实时预览**：编辑 YAML 文件时，浏览器自动刷新预览效果
|
||||
|
||||
## 📦 安装和使用
|
||||
|
||||
### 前置要求
|
||||
|
||||
- Python 3.8+
|
||||
- uv（推荐）或 pip
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 生成 PPTX 文件
|
||||
uv run yaml2pptx.py input.yaml output.pptx
|
||||
|
||||
# 自动生成输出文件名
|
||||
uv run yaml2pptx.py input.yaml # 生成 input.pptx
|
||||
|
||||
# 浏览器实时预览（新功能）
|
||||
uv run yaml2pptx.py input.yaml --preview
|
||||
|
||||
# 指定预览端口（默认随机选择 20000-30000 之间的端口）
|
||||
uv run yaml2pptx.py input.yaml --preview --port 8080
|
||||
|
||||
# 查看帮助
|
||||
uv run yaml2pptx.py --help
|
||||
```
|
||||
|
||||
### 浏览器预览功能
|
||||
|
||||
使用 `--preview` 参数可以在浏览器中实时预览 YAML 文件的效果：
|
||||
|
||||
- 启动后自动打开浏览器
|
||||
- 默认使用 20000-30000 之间的随机端口，避免端口冲突
|
||||
- 编辑 YAML 文件后，浏览器自动刷新
|
||||
- 支持所有元素类型和模板
|
||||
- 按 Ctrl+C 停止预览服务器
|
||||
|
||||
**注意**：预览效果与最终 PPTX 可能存在细微差异（字体渲染、间距等），建议最终确认时生成 PPTX 文件查看。
|
||||
|
||||
## 📖 快速开始
|
||||
|
||||
### 1. 使用模板创建演示文稿
|
||||
|
||||
```yaml
|
||||
# presentation.yaml
|
||||
metadata:
|
||||
title: "我的演示文稿"
|
||||
size: "16:9" # 16:9 或 4:3
|
||||
|
||||
slides:
|
||||
# 使用标题页模板
|
||||
- template: title_slide
|
||||
vars:
|
||||
title: "项目汇报"
|
||||
subtitle: "2026年第一季度"
|
||||
|
||||
# 使用内容页模板
|
||||
- template: content_slide
|
||||
vars:
|
||||
title: "主要成果"
|
||||
content: |
|
||||
• 销售额增长 25%
|
||||
• 客户满意度 4.8/5.0
|
||||
• 新增 3 个市场
|
||||
```
|
||||
|
||||
### 2. 自定义幻灯片
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- background:
|
||||
color: "#ffffff"
|
||||
elements:
|
||||
- type: text
|
||||
content: "自定义标题"
|
||||
box: [1, 1, 8, 1] # [x, y, width, height] 英寸
|
||||
font:
|
||||
size: 44
|
||||
bold: true
|
||||
color: "#1a1a1a"
|
||||
align: center
|
||||
|
||||
- type: shape
|
||||
shape: rectangle
|
||||
box: [2, 3, 6, 2]
|
||||
fill: "#4a90e2"
|
||||
```
|
||||
|
||||
## 📐 模板系统
|
||||
|
||||
内置模板：
|
||||
|
||||
- `title_slide`：标题页（主标题 + 副标题）
|
||||
- `content_slide`：内容页（标题条 + 内容区）
|
||||
- `two_column`：双栏布局
|
||||
|
||||
## 🧩 支持的元素类型
|
||||
|
||||
### 文本元素
|
||||
|
||||
```yaml
|
||||
- type: text
|
||||
content: "Hello World"
|
||||
box: [x, y, width, height]
|
||||
font:
|
||||
size: 32
|
||||
bold: true
|
||||
italic: false
|
||||
color: "#333333"
|
||||
align: center # left, center, right
|
||||
```
|
||||
|
||||
### 图片元素
|
||||
|
||||
```yaml
|
||||
- type: image
|
||||
src: "images/logo.png"
|
||||
box: [x, y, width, height]
|
||||
```
|
||||
|
||||
### 形状元素
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
shape: rectangle # rectangle, ellipse, rounded_rectangle
|
||||
box: [x, y, width, height]
|
||||
fill: "#4a90e2"
|
||||
line:
|
||||
color: "#000000"
|
||||
width: 2
|
||||
```
|
||||
|
||||
### 表格元素
|
||||
|
||||
```yaml
|
||||
- type: table
|
||||
position: [x, y]
|
||||
col_widths: [2, 2, 2] # 英寸
|
||||
data:
|
||||
- ["Header 1", "Header 2", "Header 3"]
|
||||
- ["Cell 1", "Cell 2", "Cell 3"]
|
||||
style:
|
||||
font_size: 14
|
||||
header_bg: "#4a90e2"
|
||||
header_color: "#ffffff"
|
||||
```
|
||||
|
||||
## 📂 项目结构
|
||||
|
||||
```
|
||||
project/
|
||||
├── templates/ # 模板定义（颜色和样式直接在模板中）
|
||||
│ ├── title_slide.yaml
|
||||
│ ├── content_slide.yaml
|
||||
│ └── two_column.yaml
|
||||
├── examples/ # 示例文件
|
||||
│ ├── demo.yaml
|
||||
│ ├── custom.yaml
|
||||
│ └── complex.yaml
|
||||
├── yaml2pptx.py # 转换脚本
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 🔧 技术栈
|
||||
|
||||
- **Python 3.8+**
|
||||
- **python-pptx**：PPTX 文件生成
|
||||
- **PyYAML**：YAML 文件解析
|
||||
- **uv**：Python 脚本运行器
|
||||
|
||||
## 📝 示例
|
||||
|
||||
查看 `examples/` 目录中的示例文件：
|
||||
|
||||
- `demo.yaml`：使用模板的完整示例（3页）
|
||||
- `custom.yaml`：自定义幻灯片示例（2页）
|
||||
- `complex.yaml`：**复杂综合示例（10页）** - 展示所有功能
|
||||
|
||||
### 复杂示例亮点
|
||||
|
||||
`complex.yaml` 是一个完整的商业计划演示文稿，包含：
|
||||
|
||||
✨ **10个精心设计的幻灯片**：
|
||||
1. 封面页（使用 title_slide 模板）
|
||||
2. 议程页（自定义布局，包含时间轴）
|
||||
3. 公司概况（使用 content_slide 模板）
|
||||
4. 市场分析（使用 two_column 模板）
|
||||
5. 产品矩阵（复杂表格 + 架构图示）
|
||||
6. 财务预测（多个表格 + 数据可视化）
|
||||
7. 团队介绍（使用 two_column 模板）
|
||||
8. 竞争优势（视觉化卡片 + SWOT 表格）
|
||||
9. 产品路线图（使用 content_slide 模板）
|
||||
10. 结束页（自定义召唤行动页）
|
||||
|
||||
🎨 **展示的功能**：
|
||||
- ✅ 所有三种模板的使用
|
||||
- ✅ 模板与自定义幻灯片混合
|
||||
- ✅ 所有元素类型：文本、形状、表格
|
||||
- ✅ 复杂布局和精确定位
|
||||
- ✅ 多种形状类型和样式组合
|
||||
- ✅ 丰富的颜色和字体样式（直接指定）
|
||||
- ✅ 大量中文内容展示
|
||||
- ✅ 表格的高级样式应用
|
||||
- ✅ 视觉化信息展示（卡片、时间轴、架构图）
|
||||
|
||||
```bash
|
||||
# 生成示例演示文稿
|
||||
uv run yaml2pptx.py examples/demo.yaml # 基础示例
|
||||
uv run yaml2pptx.py examples/custom.yaml # 自定义示例
|
||||
uv run yaml2pptx.py examples/complex.yaml # 复杂综合示例 ⭐
|
||||
```
|
||||
|
||||
**生成的文件大小**：
|
||||
- `demo_output.pptx` - 31KB
|
||||
- `custom_output.pptx` - 29KB
|
||||
- `complex_output.pptx` - 43KB (10页内容)
|
||||
|
||||
## 🎓 YAML Schema 文档
|
||||
|
||||
详细的 YAML 格式说明，请参考各类型文件的示例和注释。
|
||||
|
||||
## 🚧 限制和已知问题
|
||||
|
||||
- 原型版本，仅支持核心功能
|
||||
- 不支持复杂样式（渐变、阴影、动画等）
|
||||
- 不支持 PPTX 到 YAML 的反向解析
|
||||
- 图片背景功能暂未完整实现
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request！
|
||||
Reference in New Issue
Block a user