yaml2pptx
使用 YAML 声明式语法创建 PowerPoint 演示文稿的工具。
✨ 功能特性
- 📝 YAML 声明式语法 - 使用简单易读的 YAML 定义演示文稿
- 🎨 模板系统 - 支持参数化模板，复用幻灯片布局
- 🧩 丰富的元素类型 - 文本、图片、形状、表格
- 👁️ 实时预览 - 浏览器预览模式，支持热重载
- 📐 灵活尺寸 - 支持 16:9 和 4:3 两种宽高比
- 🔧 模块化架构 - 易于扩展和维护
🚀 快速开始
安装
本工具使用 uv 管理依赖，运行时会自动安装所需的 Python 包。
基本用法
# 生成 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
实时预览
# 启动预览服务器（自动打开浏览器）
uv run yaml2pptx.py presentation.yaml --preview
# 指定端口
uv run yaml2pptx.py presentation.yaml --preview --port 8080
预览模式会自动监听文件变化，修改 YAML 文件后浏览器会自动刷新。
📖 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 不为空时显示
🎯 命令行选项
| 选项 | 说明 |
|---|---|
input |
输入的 YAML 文件路径（必需） |
output |
输出的 PPTX 文件路径（可选） |
--template-dir |
模板文件目录 |
--preview |
启用浏览器预览模式 |
--port |
预览服务器端口（默认：随机） |
📐 坐标系统
- 单位：英寸 (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= 白色）
💡 使用技巧
- 开发流程：使用
--preview模式实时查看效果，确认无误后再生成 PPTX - 模板复用：为常用布局创建模板，保持演示文稿风格一致
- 相对路径：图片路径相对于 YAML 文件位置，便于项目管理
- 模板目录：使用模板时必须指定
--template-dir参数 - 文本换行：文本框默认启用自动换行，无需手动处理长文本
📚 完整示例
查看 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