yaml2pptx

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

✨ 功能特性

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

🚀 快速开始

安装

本工具使用 uv 管理依赖，运行时会自动安装所需的 Python 包。

基本用法

# 转换 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-dir ./templates

实时预览

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

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

# 允许局域网访问
uv run yaml2pptx.py preview presentation.yaml --host 0.0.0.0

# 不自动打开浏览器
uv run yaml2pptx.py preview presentation.yaml --no-browser

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

验证功能

在转换前验证 YAML 文件，提前发现问题：

# 独立验证命令
uv run yaml2pptx.py check presentation.yaml

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

验证功能会检查：

• ✅ YAML 语法和结构
• ✅ 元素是否超出页面范围
• ✅ 图片和模板文件是否存在
• ✅ 颜色格式是否正确
• ✅ 字体大小是否合理
• ✅ 表格数据是否一致

自动验证：转换时默认会自动验证，如果发现错误会终止转换。可以使用 --skip-validation 跳过验证：

# 跳过自动验证
uv run yaml2pptx.py convert presentation.yaml --skip-validation

验证结果示例：

🔍 正在检查 YAML 文件...

❌ 错误 (2):
  [幻灯片 2, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
  [幻灯片 3, 元素 2] 图片文件不存在: logo.png

⚠️  警告 (1):
  [幻灯片 1, 元素 1] 元素右边界超出: 10.50 > 10

检查完成: 发现 2 个错误, 1 个警告

• ERROR：阻止转换的严重问题（文件不存在、语法错误等）
• WARNING：影响视觉效果的问题（元素超出页面、字体太小等）
• INFO：优化建议

📖 YAML 语法

最小示例

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

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

使用模板

metadata:
  size: 16:9

slides:
  - template: title-slide
    vars:
      title: "我的演示文稿"
      subtitle: "使用 yaml2pptx 创建"
      author: "张三"

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

🎨 元素类型

文本元素

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

特性：文本框默认启用自动换行，文字超出宽度时会自动换行。

图片元素

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

形状元素

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

表格元素

- type: table
  position: [x, y]
  col_widths: [2, 2, 2]  # 每列宽度（英寸）
  data:
    - ["表头1", "表头2", "表头3"]
    - ["数据1", "数据2", "数据3"]
    - ["数据4", "数据5", "数据6"]
  style:
    font_size: 14
    header_bg: "#4a90e2"
    header_color: "#ffffff"

📋 模板系统

模板允许你定义可复用的幻灯片布局。

创建模板

创建模板文件 templates/title-slide.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 != ''}"  # 条件渲染
    font:
      size: 24
      align: center

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

使用模板

slides:
  - template: title-slide
    vars:
      title: "我的演示文稿"
      subtitle: "副标题"
      author: "作者"

条件渲染

使用 visible 属性控制元素显示：

- type: text
  content: "{subtitle}"
  visible: "{subtitle != ''}"  # 仅当 subtitle 不为空时显示

🎯 命令行选项

check 命令

验证 YAML 文件的正确性。

选项	说明
input	输入的 YAML 文件路径（必需）
--template-dir	模板文件目录

convert 命令

将 YAML 文件转换为 PPTX 文件。

选项	说明
input	输入的 YAML 文件路径（必需）
output	输出的 PPTX 文件路径（可选）
--template-dir	模板文件目录
--skip-validation	跳过自动验证
--force / -f	强制覆盖已存在文件

preview 命令

启动预览服务器，实时查看演示文稿效果。

选项	说明
input	输入的 YAML 文件路径（必需）
--template-dir	模板文件目录
--port	服务器端口（默认：随机端口 30000-40000）
--host	主机地址（默认：127.0.0.1）
--no-browser	不自动打开浏览器

📐 坐标系统

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

幻灯片尺寸：

• 16:9 → 10" × 5.625"
• 4:3 → 10" × 7.5"

示例：box: [1, 2, 8, 1] 表示：

• 左上角位置：(1", 2")
• 尺寸：宽 8"，高 1"

🎨 颜色格式

支持两种十六进制格式：

• 短格式：#RGB（如 #fff = 白色）
• 完整格式：#RRGGBB（如 #ffffff = 白色）

💡 使用技巧

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

📚 完整示例

查看 temp/ 目录下的示例文件：

• temp/test_refactor.yaml - 基本示例
• temp/template_demo.yaml - 模板使用示例
• temp/complex_presentation.yaml - 复杂演示文稿示例

⚠️ 常见错误

错误信息	原因	解决方法
文件不存在: xxx.yaml	找不到输入文件	检查文件路径是否正确
YAML 语法错误: 第 X 行	YAML 格式错误	检查缩进和语法
模板文件不存在: xxx	模板文件未找到	检查模板名称和 --template-dir
缺少必需变量: xxx	未提供必需的模板变量	在 vars 中提供该变量
图片文件未找到: xxx	图片文件不存在	检查图片路径

🔧 扩展性

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

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

详见 开发文档。

📦 依赖项

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

所有依赖由 uv 自动管理，无需手动安装。

🤝 贡献

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

开发者请参阅 开发文档 了解代码结构和开发规范。

📄 许可证

MIT License