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