# yaml2pptx

使用 YAML 声明式语法创建 PowerPoint 演示文稿的工具。

## 功能特性

- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
- **智能验证** - 转换前自动检查 YAML 文件，提前发现问题
- **模板系统** - 支持参数化模板，复用幻灯片布局
- **丰富的元素类型** - 文本、图片、形状、表格
- **实时预览** - 浏览器预览模式，支持热重载
- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比
- **模块化架构** - 易于扩展和维护

## 快速开始

### 安装

本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖。项目依赖在 pyproject.toml 中声明，运行时会自动安装所需的 Python 包。

### 基本用法

```bash
# 转换 YAML 为 PPTX
uv run yaml2pptx.py convert presentation.yaml output.pptx

# 自动生成输出文件名
uv run yaml2pptx.py convert presentation.yaml

# 使用模板库
uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
```

### 实时预览

```bash
# 启动预览服务器（自动打开浏览器）
uv run yaml2pptx.py preview presentation.yaml

# 指定端口
uv run yaml2pptx.py preview presentation.yaml --port 8080
```

预览模式会自动监听文件变化，修改 YAML 文件后浏览器会自动刷新。

### 验证功能

```bash
# 验证 YAML 文件
uv run yaml2pptx.py check presentation.yaml

# 使用模板时验证
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
```

## 核心概念

### YAML 语法基础

```yaml
metadata:
  size: "16:9"

slides:
  - background:
      color: "#ffffff"
    elements:
      - type: text
        box: [1, 1, 8, 1]
        content: "Hello, World!"
        font:
          size: 44
          bold: true
```

### 元素类型

#### 文本元素

```yaml
- type: text
  box: [x, y, width, height]
  content: "文本内容"
  font:
    size: 18
    bold: true
    color: "#ff0000"
```

#### 图片元素

```yaml
- type: image
  box: [x, y, width, height]
  src: "path/to/image.png"
```

#### 形状元素

```yaml
- type: shape
  box: [x, y, width, height]
  shape: rectangle
  fill: "#4a90e2"
```

#### 表格元素

```yaml
- type: table
  position: [x, y]
  col_widths: [2, 2, 2]
  data:
    - ["表头1", "表头2", "表头3"]
    - ["数据1", "数据2", "数据3"]
```

### 模板系统

#### 内联模板

```yaml
metadata:
  size: "16:9"

templates:
  title-slide:
    vars:
      - name: title
        required: true
    elements:
      - type: text
        box: [1, 2, 8, 1]
        content: "{title}"
        font:
          size: 44
          bold: true

slides:
  - template: title-slide
    vars:
      title: "我的演示文稿"
```

#### 外部模板库

```bash
# 创建 templates.yaml
uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
```

### 字体主题系统

```yaml
metadata:
  fonts:
    title:
      family: "cjk-sans"
      size: 44
      bold: true
    body:
      family: "sans"
      size: 18

slides:
  - elements:
      - type: text
        content: "标题"
        font: "@title"
```

## 常见用例

### 标题页

```yaml
metadata:
  size: "16:9"

slides:
  - elements:
      - type: text
        box: [1, 2.5, 8, 1]
        content: "项目名称"
        font:
          size: 44
          bold: true
          align: center
```

### 内容页

```yaml
slides:
  - elements:
      - type: text
        box: [1, 1, 8, 0.8]
        content: "章节标题"
        font:
          size: 32
          bold: true

      - type: text
        box: [1, 2, 8, 3]
        content: "正文内容\n支持多行文本"
        font:
          size: 18
```

### 使用模板

```yaml
metadata:
  size: "16:9"

slides:
  - template: title-slide
    vars:
      title: "第一章"
```

## 文档导航

**用户文档**

- [用户指南](docs/user-guide.md) - 完整使用指南
- [元素类型](docs/elements/) - 文本、图片、形状、表格
- [模板系统](docs/templates/) - 内联模板、外部模板库、混合模式
- [字体主题](docs/fonts.md) - 字体配置和主题管理
- [API 参考](docs/reference/) - 命令、坐标、颜色、验证
- [示例集合](docs/examples.md) - 实战示例
- [故障排查](docs/troubleshooting.md) - 常见问题

**开发文档**

- [架构设计](docs/development/architecture.md) - 代码结构和技术决策
- [模块详解](docs/development/modules/) - 各模块详细说明
- [字体系统](docs/development/font-system.md) - 字体解析实现
- [作用域系统](docs/development/scope-system.md) - 字体作用域规则
- [开发规范](docs/development/development-guide.md) - 编码规范
- [扩展指南](docs/development/extending.md) - 添加新功能
- [测试规范](docs/development/testing.md) - 测试指南

## 使用技巧

1. **开发流程**：使用预览模式实时查看效果，确认无误后再生成 PPTX
2. **模板复用**：为常用布局创建模板，保持演示文稿风格一致
3. **相对路径**：图片路径相对于 YAML 文件位置，便于项目管理
4. **文本换行**：文本框默认启用自动换行，无需手动处理长文本

## 扩展性

yaml2pptx 采用模块化架构，易于扩展：

- **添加新元素类型**：定义新的元素数据类和渲染方法
- **添加新渲染器**：支持输出到其他格式（如 PDF）
- **自定义模板**：创建符合你需求的模板库

详见 [开发文档](docs/development/extending.md)。

## 依赖项

- `python-pptx` - PowerPoint 文件生成
- `pyyaml` - YAML 解析
- `flask` - 预览服务器
- `watchdog` - 文件监听

依赖在 pyproject.toml 中声明，由 uv 自动管理，无需手动安装。

## 测试

```bash
# 运行所有测试
uv run pytest

# 运行特定类型的测试
uv run pytest tests/unit/       # 单元测试
uv run pytest tests/integration/  # 集成测试
uv run pytest tests/e2e/        # 端到端测试
```

## 贡献

欢迎贡献代码、报告问题或提出建议！

开发者请参阅 [开发文档](docs/development/) 了解代码结构和开发规范。

## 许可证

MIT License