# yaml2pptx

YAML 转 PowerPoint (PPTX) 工具 - 使用 YAML 格式的声明式语法定义演示文稿，并生成 PPTX 文件。

## 功能特性

- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
- **模板系统** - 支持参数化模板，复用幻灯片布局
- **多种元素类型** - 文本、图片、形状、表格
- **实时预览** - 浏览器预览模式，支持热重载，快速开发迭代
- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比

## 安装

脚本使用 [uv](https://github.com/astral-sh/uv) 管理 Python 依赖。运行时会自动安装所需依赖。

依赖项：
- `python-pptx` - PowerPoint 文件生成
- `pyyaml` - YAML 解析
- `flask` - 预览服务器（预览模式需要）
- `watchdog` - 文件监控（预览模式需要）

## 基本用法

### 生成 PPTX 文件

```bash
# 基本用法 - 输出文件自动生成（input.pptx）
uv run yaml2pptx.py presentation.yaml

# 指定输出文件名
uv run yaml2pptx.py presentation.yaml output.pptx

# 指定模板目录
uv run yaml2pptx.py presentation.yaml output.pptx --template-dir ./templates
```

### 实时预览模式

```bash
# 启动预览服务器（随机端口 20000-30000）
uv run yaml2pptx.py presentation.yaml --preview

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

# 指定模板目录
uv run yaml2pptx.py presentation.yaml --preview --template-dir ./templates
```

预览模式会自动打开浏览器窗口显示演示文稿，修改 YAML 文件时页面会自动刷新。

## 命令行选项

| 选项 | 说明 |
|------|------|
| `input` | 输入的 YAML 文件路径（必需） |
| `output` | 输出的 PPTX 文件路径（可选，默认为 `input.pptx`） |
| `--template-dir` | 模板 YAML 文件所在目录 |
| `--preview` | 启用浏览器预览模式（不生成 PPTX 文件） |
| `--port` | 预览服务器端口（默认：随机 20000-30000） |

## YAML 结构

### 基本演示文稿

```yaml
metadata:
  size: 16:9  # 或 4:3

slides:
  - background:
      color: "#ffffff"
    elements:
      - type: text
        box: [1, 1, 8, 1]
        content: "你好，世界！"
        font:
          size: 44
          bold: true
          color: "#333333"
          align: center
```

### 使用模板

```yaml
metadata:
  size: 16:9

slides:
  - template: title-slide
    vars:
      title: "我的演示文稿"
      subtitle: "yaml2pptx 简介"
      author: "张三"

  - template: content-slide
    vars:
      title: "功能概览"
      content: "yaml2pptx 支持多种元素类型..."
```

## 元素类型

### 文本

```yaml
- type: text
  box: [x, y, width, height]  # 位置和尺寸（单位：英寸）
  content: "文本内容"
  font:
    size: 18              # 字号（磅）
    bold: true/false      # 粗体
    italic: true/false    # 斜体
    color: "#ff0000"      # 颜色（#RGB 或 #RRGGBB）
    align: left/center/right  # 对齐方式
```

**文本自动换行**：文本框默认启用自动换行功能。当文字内容超过文本框宽度时，会自动换行显示，确保文字不会溢出边界。

### 图片

```yaml
- type: image
  box: [x, y, width, height]
  src: "path/to/image.png"  # 相对路径或绝对路径
```

### 形状

```yaml
- type: shape
  box: [x, y, width, height]
  shape: rectangle/ellipse/rounded_rectangle
  fill: "#4a90e2"           # 填充颜色
  line:
    color: "#000000"        # 边框颜色
    width: 1                # 边框宽度（磅）
```

### 表格

```yaml
- type: table
  position: [x, y]          # 表格位置
  col_widths: [2, 2, 2]     # 列宽（英寸）
  data:
    - ["表头1", "表头2", "表头3"]
    - ["行1", "数据", "数据"]
    - ["行2", "数据", "数据"]
  style:
    font_size: 14
    header_bg: "#4a90e2"
    header_color: "#ffffff"
```

## 模板系统

模板允许你定义可复用的幻灯片布局，支持参数化。

### 模板文件 (`templates/title-slide.yaml`)

```yaml
vars:
  - name: title
    required: true
  - name: subtitle
    required: false
    default: ""
  - name: author
    required: false
    default: ""

elements:
  - type: text
    box: [1, 2, 8, 1]
    content: "{title}"
    font:
      size: 44
      bold: true
      align: center

  - type: text
    box: [1, 3.5, 8, 0.5]
    content: "{subtitle}"
    visible: "{subtitle != ''}"  # 仅当 subtitle 不为空时显示
    font:
      size: 24
      align: center

  - type: text
    box: [1, 5, 8, 0.5]
    content: "{author}"
    font:
      size: 18
      align: center
```

### 使用模板

```yaml
slides:
  - template: title-slide
    vars:
      title: "我的演示文稿"
      subtitle: "演示"
      author: "李四"
```

### 模板变量说明

| 字段 | 说明 |
|------|------|
| `name` | 变量名（必需） |
| `required` | 是否必需（默认：`false`） |
| `default` | 默认值（未提供时使用） |

### 条件渲染

使用 `visible` 属性控制元素的显示条件：

```yaml
- type: text
  content: "{subtitle}"
  visible: "{subtitle != ''}"  # 仅当提供了 subtitle 时显示
```

## 背景设置

幻灯片支持纯色背景：

```yaml
slides:
  - background:
      color: "#f5f5f5"  # 浅灰色背景
    elements:
      - type: text
        content: "灰色背景上的内容"
```

## 颜色格式

颜色使用十六进制格式：
- **短格式**：`#RGB`（如 `#fff` 表示白色）
- **完整格式**：`#RRGGBB`（如 `#ffffff` 表示白色）

## 完整示例

### 演示文稿文件 (`demo.yaml`)

```yaml
metadata:
  size: 16:9

slides:
  # 使用模板的标题页
  - template: title-slide
    vars:
      title: "yaml2pptx 入门"
      subtitle: "用 YAML 编写演示文稿"

  # 自定义元素的内容页
  - background:
      color: "#ffffff"
    elements:
      - type: text
        box: [0.5, 0.5, 9, 0.8]
        content: "功能特性"
        font:
          size: 36
          bold: true
          color: "#2c3e50"

      - type: shape
        box: [0.5, 1.5, 3, 2.5]
        shape: rounded_rectangle
        fill: "#3498db"
        line:
          color: "#2980b9"
          width: 2

      - type: text
        box: [1, 2, 2, 1]
        content: "易于使用"
        font:
          size: 18
          color: "#ffffff"
          align: center

      - type: table
        position: [5, 2]
        col_widths: [2, 2]
        data:
          - ["功能", "状态"]
          - ["模板支持", "✓"]
          - ["实时预览", "✓"]
          - ["表格支持", "✓"]
        style:
          font_size: 14
          header_bg: "#2c3e50"
          header_color: "#ffffff"

  # 图片页
  - elements:
      - type: image
        box: [1, 1, 8, 4]
        src: "chart.png"
```

## 错误提示

脚本提供详细的错误信息：

| 错误 | 说明 |
|------|------|
| `文件不存在: presentation.yaml` | 找不到输入文件 |
| `YAML 语法错误: presentation.yaml, 第 5 行: ...` | YAML 语法问题 |
| `模板文件不存在: title-slide` | 模板文件未找到 |
| `缺少必需变量: title` | 未提供必需的模板变量 |
| `图片文件未找到: image.png` | 图片文件不存在 |

## 使用技巧

1. **使用模板** - 保持幻灯片布局一致
2. **启用预览模式** - 开发时快速迭代
3. **使用相对路径** - 图片路径相对于 YAML 文件位置
4. **指定模板目录** - 使用模板时必须指定 `--template-dir`
5. **先预览后生成** - 预览确认无误后再生成最终 PPTX

## 坐标系统

- **单位**：英寸 (inch)
- **原点**：幻灯片左上角
- **方向**：X 轴向右，Y 轴向下

| 尺寸比例 | 幻灯片尺寸 |
|----------|------------|
| 16:9 | 10" × 5.625" |
| 4:3 | 10" × 7.5" |

## 许可证

MIT License