lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
291 lines
6.0 KiB
Markdown
291 lines
6.0 KiB
Markdown
# yaml2pptx
|
||
|
||
使用 YAML 声明式语法创建 PowerPoint 演示文稿的工具。
|
||
|
||
## 功能特性
|
||
|
||
- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
|
||
- **智能验证** - 转换前自动检查 YAML 文件，提前发现问题
|
||
- **模板系统** - 支持参数化模板，复用幻灯片布局
|
||
- **丰富的元素类型** - 文本、图片、形状、表格
|
||
- **实时预览** - 浏览器预览模式，支持热重载
|
||
- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比
|
||
- **模块化架构** - 易于扩展和维护
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖。项目依赖在 pyproject.toml 中声明，运行时会自动安装所需的 Python 包。
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 转换 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
|
||
```
|
||
|
||
### 实时预览
|
||
|
||
```bash
|
||
# 启动预览服务器（自动打开浏览器）
|
||
uv run yaml2pptx.py preview presentation.yaml
|
||
|
||
# 指定端口
|
||
uv run yaml2pptx.py preview presentation.yaml --port 8080
|
||
```
|
||
|
||
预览模式会自动监听文件变化，修改 YAML 文件后浏览器会自动刷新。
|
||
|
||
### 验证功能
|
||
|
||
```bash
|
||
# 验证 YAML 文件
|
||
uv run yaml2pptx.py check presentation.yaml
|
||
|
||
# 使用模板时验证
|
||
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
|
||
```
|
||
|
||
## 核心概念
|
||
|
||
### YAML 语法基础
|
||
|
||
```yaml
|
||
metadata:
|
||
size: "16:9"
|
||
|
||
slides:
|
||
- background:
|
||
color: "#ffffff"
|
||
elements:
|
||
- type: text
|
||
box: [1, 1, 8, 1]
|
||
content: "Hello, World!"
|
||
font:
|
||
size: 44
|
||
bold: true
|
||
```
|
||
|
||
### 元素类型
|
||
|
||
#### 文本元素
|
||
|
||
```yaml
|
||
- type: text
|
||
box: [x, y, width, height]
|
||
content: "文本内容"
|
||
font:
|
||
size: 18
|
||
bold: true
|
||
color: "#ff0000"
|
||
```
|
||
|
||
#### 图片元素
|
||
|
||
```yaml
|
||
- type: image
|
||
box: [x, y, width, height]
|
||
src: "path/to/image.png"
|
||
```
|
||
|
||
#### 形状元素
|
||
|
||
```yaml
|
||
- type: shape
|
||
box: [x, y, width, height]
|
||
shape: rectangle
|
||
fill: "#4a90e2"
|
||
```
|
||
|
||
#### 表格元素
|
||
|
||
```yaml
|
||
- type: table
|
||
position: [x, y]
|
||
col_widths: [2, 2, 2]
|
||
data:
|
||
- ["表头1", "表头2", "表头3"]
|
||
- ["数据1", "数据2", "数据3"]
|
||
```
|
||
|
||
### 模板系统
|
||
|
||
#### 内联模板
|
||
|
||
```yaml
|
||
metadata:
|
||
size: "16:9"
|
||
|
||
templates:
|
||
title-slide:
|
||
vars:
|
||
- name: title
|
||
required: true
|
||
elements:
|
||
- type: text
|
||
box: [1, 2, 8, 1]
|
||
content: "{title}"
|
||
font:
|
||
size: 44
|
||
bold: true
|
||
|
||
slides:
|
||
- template: title-slide
|
||
vars:
|
||
title: "我的演示文稿"
|
||
```
|
||
|
||
#### 外部模板库
|
||
|
||
```bash
|
||
# 创建 templates.yaml
|
||
uv run yaml2pptx.py convert presentation.yaml output.pptx --template ./templates.yaml
|
||
```
|
||
|
||
### 字体主题系统
|
||
|
||
```yaml
|
||
metadata:
|
||
fonts:
|
||
title:
|
||
family: "cjk-sans"
|
||
size: 44
|
||
bold: true
|
||
body:
|
||
family: "sans"
|
||
size: 18
|
||
|
||
slides:
|
||
- elements:
|
||
- type: text
|
||
content: "标题"
|
||
font: "@title"
|
||
```
|
||
|
||
## 常见用例
|
||
|
||
### 标题页
|
||
|
||
```yaml
|
||
metadata:
|
||
size: "16:9"
|
||
|
||
slides:
|
||
- elements:
|
||
- type: text
|
||
box: [1, 2.5, 8, 1]
|
||
content: "项目名称"
|
||
font:
|
||
size: 44
|
||
bold: true
|
||
align: center
|
||
```
|
||
|
||
### 内容页
|
||
|
||
```yaml
|
||
slides:
|
||
- elements:
|
||
- type: text
|
||
box: [1, 1, 8, 0.8]
|
||
content: "章节标题"
|
||
font:
|
||
size: 32
|
||
bold: true
|
||
|
||
- type: text
|
||
box: [1, 2, 8, 3]
|
||
content: "正文内容\n支持多行文本"
|
||
font:
|
||
size: 18
|
||
```
|
||
|
||
### 使用模板
|
||
|
||
```yaml
|
||
metadata:
|
||
size: "16:9"
|
||
|
||
slides:
|
||
- template: title-slide
|
||
vars:
|
||
title: "第一章"
|
||
```
|
||
|
||
## 文档导航
|
||
|
||
**用户文档**
|
||
|
||
- [用户指南](docs/user-guide.md) - 完整使用指南
|
||
- [元素类型](docs/elements/) - 文本、图片、形状、表格
|
||
- [模板系统](docs/templates/) - 内联模板、外部模板库、混合模式
|
||
- [字体主题](docs/fonts.md) - 字体配置和主题管理
|
||
- [API 参考](docs/reference/) - 命令、坐标、颜色、验证
|
||
- [示例集合](docs/examples.md) - 实战示例
|
||
- [故障排查](docs/troubleshooting.md) - 常见问题
|
||
|
||
**开发文档**
|
||
|
||
- [架构设计](docs/development/architecture.md) - 代码结构和技术决策
|
||
- [模块详解](docs/development/modules/) - 各模块详细说明
|
||
- [字体系统](docs/development/font-system.md) - 字体解析实现
|
||
- [作用域系统](docs/development/scope-system.md) - 字体作用域规则
|
||
- [开发规范](docs/development/development-guide.md) - 编码规范
|
||
- [扩展指南](docs/development/extending.md) - 添加新功能
|
||
- [测试规范](docs/development/testing.md) - 测试指南
|
||
|
||
## 使用技巧
|
||
|
||
1. **开发流程**：使用预览模式实时查看效果，确认无误后再生成 PPTX
|
||
2. **模板复用**：为常用布局创建模板，保持演示文稿风格一致
|
||
3. **相对路径**：图片路径相对于 YAML 文件位置，便于项目管理
|
||
4. **文本换行**：文本框默认启用自动换行，无需手动处理长文本
|
||
|
||
## 扩展性
|
||
|
||
yaml2pptx 采用模块化架构，易于扩展：
|
||
|
||
- **添加新元素类型**：定义新的元素数据类和渲染方法
|
||
- **添加新渲染器**：支持输出到其他格式（如 PDF）
|
||
- **自定义模板**：创建符合你需求的模板库
|
||
|
||
详见 [开发文档](docs/development/extending.md)。
|
||
|
||
## 依赖项
|
||
|
||
- `python-pptx` - PowerPoint 文件生成
|
||
- `pyyaml` - YAML 解析
|
||
- `flask` - 预览服务器
|
||
- `watchdog` - 文件监听
|
||
|
||
依赖在 pyproject.toml 中声明，由 uv 自动管理，无需手动安装。
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
uv run pytest
|
||
|
||
# 运行特定类型的测试
|
||
uv run pytest tests/unit/ # 单元测试
|
||
uv run pytest tests/integration/ # 集成测试
|
||
uv run pytest tests/e2e/ # 端到端测试
|
||
```
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献代码、报告问题或提出建议！
|
||
|
||
开发者请参阅 [开发文档](docs/development/) 了解代码结构和开发规范。
|
||
|
||
## 许可证
|
||
|
||
MIT License
|