Files

lanyuanxiaoyao cd7988cbd5 feat: initial implementation of html2pptx with OpenSpec documentation

Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint:
- Element rendering: text, image, shape, table, chart
- Template system with placeholders
- PPTX generation with python-pptx

OpenSpec workflow setup:
- 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx
- 7 main specifications covering all core modules
- Config and documentation structure

30 files changed, 4984 insertions(+)

2026-03-02 14:28:25 +08:00

6.0 KiB

Raw Blame History

YAML to PPTX Converter

将 YAML 格式的演示文稿源文件转换为 PPTX 文件，让 AI 也能轻松生成高质量的演示文稿。

🎯 核心特性

人类和 AI 友好：使用 YAML 格式，简洁可读，易于生成
模板系统：可复用的幻灯片布局，大幅减少重复配置
核心元素支持：文本、图片、形状、表格
精确布局控制：基于英寸单位的精确定位
简洁设计：颜色和样式直接在模板中定义，无需额外配置
浏览器实时预览：编辑 YAML 文件时，浏览器自动刷新预览效果

📦 安装和使用

前置要求

Python 3.8+
uv（推荐）或 pip

使用方法

# 生成 PPTX 文件
uv run yaml2pptx.py input.yaml output.pptx

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

# 浏览器实时预览（新功能）
uv run yaml2pptx.py input.yaml --preview

# 指定预览端口（默认随机选择 20000-30000 之间的端口）
uv run yaml2pptx.py input.yaml --preview --port 8080

# 查看帮助
uv run yaml2pptx.py --help

浏览器预览功能

使用 --preview 参数可以在浏览器中实时预览 YAML 文件的效果：

启动后自动打开浏览器
默认使用 20000-30000 之间的随机端口，避免端口冲突
编辑 YAML 文件后，浏览器自动刷新
支持所有元素类型和模板
按 Ctrl+C 停止预览服务器

注意：预览效果与最终 PPTX 可能存在细微差异（字体渲染、间距等），建议最终确认时生成 PPTX 文件查看。

📖 快速开始

1. 使用模板创建演示文稿

# presentation.yaml
metadata:
  title: "我的演示文稿"
  size: "16:9"  # 16:9 或 4:3

slides:
  # 使用标题页模板
  - template: title_slide
    vars:
      title: "项目汇报"
      subtitle: "2026年第一季度"

  # 使用内容页模板
  - template: content_slide
    vars:
      title: "主要成果"
      content: |
        • 销售额增长 25%
        • 客户满意度 4.8/5.0
        • 新增 3 个市场

2. 自定义幻灯片

slides:
  - background:
      color: "#ffffff"
    elements:
      - type: text
        content: "自定义标题"
        box: [1, 1, 8, 1]  # [x, y, width, height] 英寸
        font:
          size: 44
          bold: true
          color: "#1a1a1a"
          align: center

      - type: shape
        shape: rectangle
        box: [2, 3, 6, 2]
        fill: "#4a90e2"

📐 模板系统

内置模板：

title_slide：标题页（主标题 + 副标题）
content_slide：内容页（标题条 + 内容区）
two_column：双栏布局

🧩 支持的元素类型

文本元素

- type: text
  content: "Hello World"
  box: [x, y, width, height]
  font:
    size: 32
    bold: true
    italic: false
    color: "#333333"
    align: center  # left, center, right

图片元素

- type: image
  src: "images/logo.png"
  box: [x, y, width, height]

形状元素

- type: shape
  shape: rectangle  # rectangle, ellipse, rounded_rectangle
  box: [x, y, width, height]
  fill: "#4a90e2"
  line:
    color: "#000000"
    width: 2

表格元素

- type: table
  position: [x, y]
  col_widths: [2, 2, 2]  # 英寸
  data:
    - ["Header 1", "Header 2", "Header 3"]
    - ["Cell 1", "Cell 2", "Cell 3"]
  style:
    font_size: 14
    header_bg: "#4a90e2"
    header_color: "#ffffff"

📂 项目结构

project/
├── templates/           # 模板定义（颜色和样式直接在模板中）
│   ├── title_slide.yaml
│   ├── content_slide.yaml
│   └── two_column.yaml
├── examples/            # 示例文件
│   ├── demo.yaml
│   ├── custom.yaml
│   └── complex.yaml
├── yaml2pptx.py         # 转换脚本
└── README.md

🔧 技术栈

Python 3.8+
python-pptx：PPTX 文件生成
PyYAML：YAML 文件解析
uv：Python 脚本运行器

📝 示例

查看 examples/ 目录中的示例文件：

demo.yaml：使用模板的完整示例（3页）
custom.yaml：自定义幻灯片示例（2页）
complex.yaml：复杂综合示例（10页） - 展示所有功能

复杂示例亮点

complex.yaml 是一个完整的商业计划演示文稿，包含：

✨ 10个精心设计的幻灯片：

封面页（使用 title_slide 模板）
议程页（自定义布局，包含时间轴）
公司概况（使用 content_slide 模板）
市场分析（使用 two_column 模板）
产品矩阵（复杂表格 + 架构图示）
财务预测（多个表格 + 数据可视化）
团队介绍（使用 two_column 模板）
竞争优势（视觉化卡片 + SWOT 表格）
产品路线图（使用 content_slide 模板）
结束页（自定义召唤行动页）

🎨 展示的功能：

✅ 所有三种模板的使用
✅ 模板与自定义幻灯片混合
✅ 所有元素类型：文本、形状、表格
✅ 复杂布局和精确定位
✅ 多种形状类型和样式组合
✅ 丰富的颜色和字体样式（直接指定）
✅ 大量中文内容展示
✅ 表格的高级样式应用
✅ 视觉化信息展示（卡片、时间轴、架构图）

# 生成示例演示文稿
uv run yaml2pptx.py examples/demo.yaml        # 基础示例
uv run yaml2pptx.py examples/custom.yaml      # 自定义示例
uv run yaml2pptx.py examples/complex.yaml     # 复杂综合示例 ⭐

生成的文件大小：

demo_output.pptx - 31KB
custom_output.pptx - 29KB
complex_output.pptx - 43KB (10页内容)

🎓 YAML Schema 文档

详细的 YAML 格式说明，请参考各类型文件的示例和注释。

🚧 限制和已知问题

原型版本，仅支持核心功能
不支持复杂样式（渐变、阴影、动画等）
不支持 PPTX 到 YAML 的反向解析
图片背景功能暂未完整实现

📄 License

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

6.0 KiB Raw Blame History Unescape Escape