lanyuanxiaoyao
b2132dc06b
- Set text_frame.word_wrap = True in add_text_element() for PPTX - Change CSS from white-space: pre-wrap to normal in HTML preview - Add overflow-wrap: break-word for better word breaking - Update README.md with auto-wrap documentation - Update element-rendering and html-rendering specs - Archive change: 2026-03-02-add-text-auto-wrap
345 lines
7.6 KiB
Markdown
345 lines
7.6 KiB
Markdown
# yaml2pptx
|
||
|
||
YAML 转 PowerPoint (PPTX) 工具 - 使用 YAML 格式的声明式语法定义演示文稿，并生成 PPTX 文件。
|
||
|
||
## 功能特性
|
||
|
||
- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
|
||
- **模板系统** - 支持参数化模板，复用幻灯片布局
|
||
- **多种元素类型** - 文本、图片、形状、表格
|
||
- **实时预览** - 浏览器预览模式，支持热重载，快速开发迭代
|
||
- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比
|
||
|
||
## 安装
|
||
|
||
脚本使用 [uv](https://github.com/astral-sh/uv) 管理 Python 依赖。运行时会自动安装所需依赖。
|
||
|
||
依赖项：
|
||
- `python-pptx` - PowerPoint 文件生成
|
||
- `pyyaml` - YAML 解析
|
||
- `flask` - 预览服务器（预览模式需要）
|
||
- `watchdog` - 文件监控（预览模式需要）
|
||
|
||
## 基本用法
|
||
|
||
### 生成 PPTX 文件
|
||
|
||
```bash
|
||
# 基本用法 - 输出文件自动生成（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
|
||
```
|
||
|
||
### 实时预览模式
|
||
|
||
```bash
|
||
# 启动预览服务器（随机端口 20000-30000）
|
||
uv run yaml2pptx.py presentation.yaml --preview
|
||
|
||
# 指定端口
|
||
uv run yaml2pptx.py presentation.yaml --preview --port 8080
|
||
|
||
# 指定模板目录
|
||
uv run yaml2pptx.py presentation.yaml --preview --template-dir ./templates
|
||
```
|
||
|
||
预览模式会自动打开浏览器窗口显示演示文稿，修改 YAML 文件时页面会自动刷新。
|
||
|
||
## 命令行选项
|
||
|
||
| 选项 | 说明 |
|
||
|------|------|
|
||
| `input` | 输入的 YAML 文件路径（必需） |
|
||
| `output` | 输出的 PPTX 文件路径（可选，默认为 `input.pptx`） |
|
||
| `--template-dir` | 模板 YAML 文件所在目录 |
|
||
| `--preview` | 启用浏览器预览模式（不生成 PPTX 文件） |
|
||
| `--port` | 预览服务器端口（默认：随机 20000-30000） |
|
||
|
||
## YAML 结构
|
||
|
||
### 基本演示文稿
|
||
|
||
```yaml
|
||
metadata:
|
||
size: 16:9 # 或 4:3
|
||
|
||
slides:
|
||
- background:
|
||
color: "#ffffff"
|
||
elements:
|
||
- type: text
|
||
box: [1, 1, 8, 1]
|
||
content: "你好，世界！"
|
||
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/false # 粗体
|
||
italic: true/false # 斜体
|
||
color: "#ff0000" # 颜色（#RGB 或 #RRGGBB）
|
||
align: 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/ellipse/rounded_rectangle
|
||
fill: "#4a90e2" # 填充颜色
|
||
line:
|
||
color: "#000000" # 边框颜色
|
||
width: 1 # 边框宽度（磅）
|
||
```
|
||
|
||
### 表格
|
||
|
||
```yaml
|
||
- type: table
|
||
position: [x, y] # 表格位置
|
||
col_widths: [2, 2, 2] # 列宽（英寸）
|
||
data:
|
||
- ["表头1", "表头2", "表头3"]
|
||
- ["行1", "数据", "数据"]
|
||
- ["行2", "数据", "数据"]
|
||
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 != ''}" # 仅当 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: "李四"
|
||
```
|
||
|
||
### 模板变量说明
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `name` | 变量名（必需） |
|
||
| `required` | 是否必需（默认：`false`） |
|
||
| `default` | 默认值（未提供时使用） |
|
||
|
||
### 条件渲染
|
||
|
||
使用 `visible` 属性控制元素的显示条件：
|
||
|
||
```yaml
|
||
- type: text
|
||
content: "{subtitle}"
|
||
visible: "{subtitle != ''}" # 仅当提供了 subtitle 时显示
|
||
```
|
||
|
||
## 背景设置
|
||
|
||
幻灯片支持纯色背景：
|
||
|
||
```yaml
|
||
slides:
|
||
- background:
|
||
color: "#f5f5f5" # 浅灰色背景
|
||
elements:
|
||
- type: text
|
||
content: "灰色背景上的内容"
|
||
```
|
||
|
||
## 颜色格式
|
||
|
||
颜色使用十六进制格式：
|
||
- **短格式**：`#RGB`（如 `#fff` 表示白色）
|
||
- **完整格式**：`#RRGGBB`（如 `#ffffff` 表示白色）
|
||
|
||
## 完整示例
|
||
|
||
### 演示文稿文件 (`demo.yaml`)
|
||
|
||
```yaml
|
||
metadata:
|
||
size: 16:9
|
||
|
||
slides:
|
||
# 使用模板的标题页
|
||
- template: title-slide
|
||
vars:
|
||
title: "yaml2pptx 入门"
|
||
subtitle: "用 YAML 编写演示文稿"
|
||
|
||
# 自定义元素的内容页
|
||
- background:
|
||
color: "#ffffff"
|
||
elements:
|
||
- type: text
|
||
box: [0.5, 0.5, 9, 0.8]
|
||
content: "功能特性"
|
||
font:
|
||
size: 36
|
||
bold: true
|
||
color: "#2c3e50"
|
||
|
||
- type: shape
|
||
box: [0.5, 1.5, 3, 2.5]
|
||
shape: rounded_rectangle
|
||
fill: "#3498db"
|
||
line:
|
||
color: "#2980b9"
|
||
width: 2
|
||
|
||
- type: text
|
||
box: [1, 2, 2, 1]
|
||
content: "易于使用"
|
||
font:
|
||
size: 18
|
||
color: "#ffffff"
|
||
align: center
|
||
|
||
- type: table
|
||
position: [5, 2]
|
||
col_widths: [2, 2]
|
||
data:
|
||
- ["功能", "状态"]
|
||
- ["模板支持", "✓"]
|
||
- ["实时预览", "✓"]
|
||
- ["表格支持", "✓"]
|
||
style:
|
||
font_size: 14
|
||
header_bg: "#2c3e50"
|
||
header_color: "#ffffff"
|
||
|
||
# 图片页
|
||
- elements:
|
||
- type: image
|
||
box: [1, 1, 8, 4]
|
||
src: "chart.png"
|
||
```
|
||
|
||
## 错误提示
|
||
|
||
脚本提供详细的错误信息：
|
||
|
||
| 错误 | 说明 |
|
||
|------|------|
|
||
| `文件不存在: presentation.yaml` | 找不到输入文件 |
|
||
| `YAML 语法错误: presentation.yaml, 第 5 行: ...` | YAML 语法问题 |
|
||
| `模板文件不存在: title-slide` | 模板文件未找到 |
|
||
| `缺少必需变量: title` | 未提供必需的模板变量 |
|
||
| `图片文件未找到: image.png` | 图片文件不存在 |
|
||
|
||
## 使用技巧
|
||
|
||
1. **使用模板** - 保持幻灯片布局一致
|
||
2. **启用预览模式** - 开发时快速迭代
|
||
3. **使用相对路径** - 图片路径相对于 YAML 文件位置
|
||
4. **指定模板目录** - 使用模板时必须指定 `--template-dir`
|
||
5. **先预览后生成** - 预览确认无误后再生成最终 PPTX
|
||
|
||
## 坐标系统
|
||
|
||
- **单位**：英寸 (inch)
|
||
- **原点**：幻灯片左上角
|
||
- **方向**：X 轴向右，Y 轴向下
|
||
|
||
| 尺寸比例 | 幻灯片尺寸 |
|
||
|----------|------------|
|
||
| 16:9 | 10" × 5.625" |
|
||
| 4:3 | 10" × 7.5" |
|
||
|
||
## 许可证
|
||
|
||
MIT License
|