lanyuanxiaoyao
66472cbd86
重构命令行接口，建立清晰的子命令架构，提升用户体验和代码可维护性。 主要变更： - 移除传统模式，统一使用子命令架构（check/convert/preview） - 将 preview 从 convert 的标志独立为子命令，职责分离 - 重命名参数：--no-check → --skip-validation - 新增 --force/-f：convert 命令支持强制覆盖已存在文件 - 新增 --host：preview 命令支持配置主机地址（局域网预览） - 新增 --no-browser：preview 命令支持不自动打开浏览器 - 优化 --port 默认值：从固定端口改为随机端口（30000-40000） 破坏性变更： - 不再支持传统模式（yaml2pptx.py input.yaml output.pptx） - convert 命令不再支持 --preview 参数，需使用 preview 子命令 文档更新： - 更新 README.md 和 README_DEV.md 的所有使用示例 - 更新命令行选项说明表格 - 新增 CLI 接口规范文档 OpenSpec： - 创建 cli-interface 规范（新能力） - 更新 browser-preview-server 规范（修改的能力） - 归档 refactor-cli-args change（45/45 任务完成）
366 lines
8.7 KiB
Markdown
366 lines
8.7 KiB
Markdown
# yaml2pptx
|
||
|
||
使用 YAML 声明式语法创建 PowerPoint 演示文稿的工具。
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 📝 **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
|
||
- ✅ **智能验证** - 转换前自动检查 YAML 文件，提前发现问题
|
||
- 🎨 **模板系统** - 支持参数化模板，复用幻灯片布局
|
||
- 🧩 **丰富的元素类型** - 文本、图片、形状、表格
|
||
- 👁️ **实时预览** - 浏览器预览模式，支持热重载
|
||
- 📐 **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比
|
||
- 🔧 **模块化架构** - 易于扩展和维护
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 安装
|
||
|
||
本工具使用 [uv](https://github.com/astral-sh/uv) 管理依赖，运行时会自动安装所需的 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-dir ./templates
|
||
```
|
||
|
||
### 实时预览
|
||
|
||
```bash
|
||
# 启动预览服务器（自动打开浏览器）
|
||
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 文件，提前发现问题：
|
||
|
||
```bash
|
||
# 独立验证命令
|
||
uv run yaml2pptx.py check presentation.yaml
|
||
|
||
# 使用模板时验证
|
||
uv run yaml2pptx.py check presentation.yaml --template-dir ./templates
|
||
```
|
||
|
||
验证功能会检查：
|
||
- ✅ YAML 语法和结构
|
||
- ✅ 元素是否超出页面范围
|
||
- ✅ 图片和模板文件是否存在
|
||
- ✅ 颜色格式是否正确
|
||
- ✅ 字体大小是否合理
|
||
- ✅ 表格数据是否一致
|
||
|
||
**自动验证**：转换时默认会自动验证，如果发现错误会终止转换。可以使用 `--skip-validation` 跳过验证：
|
||
|
||
```bash
|
||
# 跳过自动验证
|
||
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 语法
|
||
|
||
### 最小示例
|
||
|
||
```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
|
||
```
|
||
|
||
### 使用模板
|
||
|
||
```yaml
|
||
metadata:
|
||
size: 16:9
|
||
|
||
slides:
|
||
- template: title-slide
|
||
vars:
|
||
title: "我的演示文稿"
|
||
subtitle: "使用 yaml2pptx 创建"
|
||
author: "张三"
|
||
|
||
- template: content-slide
|
||
vars:
|
||
title: "功能概览"
|
||
content: "yaml2pptx 支持多种元素类型..."
|
||
```
|
||
|
||
## 🎨 元素类型
|
||
|
||
### 文本元素
|
||
|
||
```yaml
|
||
- type: text
|
||
box: [x, y, width, height] # 位置和尺寸（英寸）
|
||
content: "文本内容"
|
||
font:
|
||
size: 18 # 字号（磅）
|
||
bold: true # 粗体
|
||
italic: false # 斜体
|
||
color: "#ff0000" # 颜色
|
||
align: center # left/center/right
|
||
```
|
||
|
||
**特性**：文本框默认启用自动换行，文字超出宽度时会自动换行。
|
||
|
||
### 图片元素
|
||
|
||
```yaml
|
||
- type: image
|
||
box: [x, y, width, height]
|
||
src: "path/to/image.png" # 支持相对路径和绝对路径
|
||
```
|
||
|
||
### 形状元素
|
||
|
||
```yaml
|
||
- type: shape
|
||
box: [x, y, width, height]
|
||
shape: rectangle # rectangle/ellipse/rounded_rectangle
|
||
fill: "#4a90e2" # 填充颜色
|
||
line:
|
||
color: "#000000" # 边框颜色
|
||
width: 2 # 边框宽度（磅）
|
||
```
|
||
|
||
### 表格元素
|
||
|
||
```yaml
|
||
- 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`：
|
||
|
||
```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
|
||
```
|
||
|
||
### 使用模板
|
||
|
||
```yaml
|
||
slides:
|
||
- template: title-slide
|
||
vars:
|
||
title: "我的演示文稿"
|
||
subtitle: "副标题"
|
||
author: "作者"
|
||
```
|
||
|
||
### 条件渲染
|
||
|
||
使用 `visible` 属性控制元素显示：
|
||
|
||
```yaml
|
||
- type: text
|
||
content: "{subtitle}"
|
||
visible: "{subtitle != ''}" # 仅当 subtitle 不为空时显示
|
||
```
|
||
|
||
## 🎯 命令行选项
|
||
|
||
### check 命令
|
||
|
||
验证 YAML 文件的正确性。
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `input` | 输入的 YAML 文件路径（必需） |
|
||
| `--template-dir` | 模板文件目录 |
|
||
|
||
### convert 命令
|
||
|
||
将 YAML 文件转换为 PPTX 文件。
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `input` | 输入的 YAML 文件路径（必需） |
|
||
| `output` | 输出的 PPTX 文件路径（可选） |
|
||
| `--template-dir` | 模板文件目录 |
|
||
| `--skip-validation` | 跳过自动验证 |
|
||
| `--force` / `-f` | 强制覆盖已存在文件 |
|
||
|
||
### preview 命令
|
||
|
||
启动预览服务器，实时查看演示文稿效果。
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `input` | 输入的 YAML 文件路径（必需） |
|
||
| `--template-dir` | 模板文件目录 |
|
||
| `--port` | 服务器端口（默认：随机端口 30000-40000） |
|
||
| `--host` | 主机地址（默认：127.0.0.1） |
|
||
| `--no-browser` | 不自动打开浏览器 |
|
||
|
||
## 📐 坐标系统
|
||
|
||
- **单位**：英寸 (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` = 白色）
|
||
|
||
## 💡 使用技巧
|
||
|
||
1. **开发流程**：使用 `--preview` 模式实时查看效果，确认无误后再生成 PPTX
|
||
2. **模板复用**：为常用布局创建模板，保持演示文稿风格一致
|
||
3. **相对路径**：图片路径相对于 YAML 文件位置，便于项目管理
|
||
4. **模板目录**：使用模板时必须指定 `--template-dir` 参数
|
||
5. **文本换行**：文本框默认启用自动换行，无需手动处理长文本
|
||
|
||
## 📚 完整示例
|
||
|
||
查看 `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）
|
||
- **自定义模板**：创建符合你需求的模板库
|
||
|
||
详见 [开发文档](README_DEV.md)。
|
||
|
||
## 📦 依赖项
|
||
|
||
- `python-pptx` - PowerPoint 文件生成
|
||
- `pyyaml` - YAML 解析
|
||
- `flask` - 预览服务器
|
||
- `watchdog` - 文件监听
|
||
|
||
所有依赖由 uv 自动管理，无需手动安装。
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献代码、报告问题或提出建议！
|
||
|
||
开发者请参阅 [开发文档](README_DEV.md) 了解代码结构和开发规范。
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|