Files

lanyuanxiaoyao 124ef0e5ce refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷：
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行，仅保留概览和导航
- 删除 README_DEV.md，内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure

2026-03-06 15:11:36 +08:00

5.4 KiB

Raw Blame History

用户指南

本指南提供 yaml2pptx 的完整使用说明。

功能特性

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

安装

本工具使用 uv 管理依赖。项目依赖在 pyproject.toml 中声明，运行时会自动安装所需的 Python 包。

基本用法

转换 YAML 为 PPTX

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

实时预览

# 启动预览服务器（自动打开浏览器）
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 ./templates.yaml

验证功能会检查：

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

description 字段

metadata.description 字段用于描述整个演示文稿的概要和用途，仅用于文档目的，不影响生成的 PPTX 文件：

metadata:
  size: "16:9"
  description: "2024年度项目进展总结，包含背景、成果和展望"

使用模板

metadata:
  size: "16:9"

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

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

使用技巧

开发流程：使用预览模式实时查看效果，确认无误后再生成 PPTX
模板复用：为常用布局创建模板，保持演示文稿风格一致
相对路径：图片路径相对于 YAML 文件位置，便于项目管理
文本换行：文本框默认启用自动换行，无需手动处理长文本

扩展性

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

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

详见开发文档。

依赖项

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

依赖在 pyproject.toml 中声明，由 uv 自动管理，无需手动安装。

测试

项目包含完整的测试套件，使用 pytest 框架。

运行测试

# 安装测试依赖
uv pip install -e ".[dev]"

# 运行所有测试
uv run pytest

# 运行特定类型的测试
uv run pytest tests/unit/       # 单元测试
uv run pytest tests/integration/  # 集成测试
uv run pytest tests/e2e/        # 端到端测试

# 运行特定测试文件
uv run pytest tests/unit/test_elements.py

# 显示详细输出
uv run pytest -v

# 显示测试覆盖率
uv run pytest --cov=. --cov-report=html

测试结构

tests/
├── unit/           # 单元测试 - 测试各模块独立功能
├── integration/    # 集成测试 - 测试模块间协作
├── e2e/            # 端到端测试 - 测试完整用户场景
└── fixtures/       # 测试数据

贡献

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

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

许可证

MIT License

5.4 KiB Raw Blame History Unescape Escape