yaml2pptx

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

功能特性

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

安装

脚本使用 uv 管理 Python 依赖。运行时会自动安装所需依赖。

依赖项：

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

基本用法

生成 PPTX 文件

# 基本用法 - 输出文件自动生成（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

实时预览模式

# 启动预览服务器（随机端口 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 结构

基本演示文稿

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

使用模板

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/false      # 粗体
    italic: true/false    # 斜体
    color: "#ff0000"      # 颜色（#RGB 或 #RRGGBB）
    align: left/center/right  # 对齐方式

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

图片

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

形状

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

表格

- 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)

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

使用模板

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

模板变量说明

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

条件渲染

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

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

背景设置

幻灯片支持纯色背景：

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

颜色格式

颜色使用十六进制格式：

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

完整示例

演示文稿文件 (demo.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