feat: enable text auto-wrap for text boxes by default

- 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
2026-03-02 15:23:14 +08:00
parent cd7988cbd5
commit b2132dc06b
11 changed files with 500 additions and 173 deletions
--- a/README.md
+++ b/README.md
@@ -1,247 +1,344 @@
-# YAML to PPTX Converter
+# yaml2pptx

-将 YAML 格式的演示文稿源文件转换为 PPTX 文件，让 AI 也能轻松生成高质量的演示文稿。
+YAML 转 PowerPoint (PPTX) 工具 - 使用 YAML 格式的声明式语法定义演示文稿，并生成 PPTX 文件。

-## 🎯 核心特性
+## 功能特性

- **人类和 AI 友好**：使用 YAML 格式，简洁可读，易于生成
- **模板系统**：可复用的幻灯片布局，大幅减少重复配置
- **核心元素支持**：文本、图片、形状、表格
- **精确布局控制**：基于英寸单位的精确定位
- **简洁设计**：颜色和样式直接在模板中定义，无需额外配置
- **浏览器实时预览**：编辑 YAML 文件时，浏览器自动刷新预览效果
+- **YAML 声明式语法** - 使用简单易读的 YAML 定义演示文稿
+- **模板系统** - 支持参数化模板，复用幻灯片布局
+- **多种元素类型** - 文本、图片、形状、表格
+- **实时预览** - 浏览器预览模式，支持热重载，快速开发迭代
+- **灵活尺寸** - 支持 16:9 和 4:3 两种宽高比

-## 📦 安装和使用
+## 安装

-### 前置要求
+脚本使用 [uv](https://github.com/astral-sh/uv) 管理 Python 依赖。运行时会自动安装所需依赖。

- Python 3.8+
- uv（推荐）或 pip
+依赖项：
+- `python-pptx` - PowerPoint 文件生成
+- `pyyaml` - YAML 解析
+- `flask` - 预览服务器（预览模式需要）
+- `watchdog` - 文件监控（预览模式需要）

-### 使用方法
+## 基本用法
+
+### 生成 PPTX 文件

 ```bash
-# 生成 PPTX 文件
-uv run yaml2pptx.py input.yaml output.pptx
+# 基本用法 - 输出文件自动生成（input.pptx）
+uv run yaml2pptx.py presentation.yaml

-# 自动生成输出文件名
-uv run yaml2pptx.py input.yaml  # 生成 input.pptx
+# 指定输出文件名
+uv run yaml2pptx.py presentation.yaml output.pptx

-# 浏览器实时预览（新功能）
-uv run yaml2pptx.py input.yaml --preview
-
-# 指定预览端口（默认随机选择 20000-30000 之间的端口）
-uv run yaml2pptx.py input.yaml --preview --port 8080
-
-# 查看帮助
-uv run yaml2pptx.py --help
+# 指定模板目录
+uv run yaml2pptx.py presentation.yaml output.pptx --template-dir ./templates
 ```

-### 浏览器预览功能
+### 实时预览模式

-使用 `--preview` 参数可以在浏览器中实时预览 YAML 文件的效果：
+```bash
+# 启动预览服务器（随机端口 20000-30000）
+uv run yaml2pptx.py presentation.yaml --preview

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

-**注意**：预览效果与最终 PPTX 可能存在细微差异（字体渲染、间距等），建议最终确认时生成 PPTX 文件查看。
+# 指定模板目录
+uv run yaml2pptx.py presentation.yaml --preview --template-dir ./templates
+```

-## 📖 快速开始
+预览模式会自动打开浏览器窗口显示演示文稿，修改 YAML 文件时页面会自动刷新。

-### 1. 使用模板创建演示文稿
+## 命令行选项
+
+| 选项 | 说明 |
+|------|------|
+| `input` | 输入的 YAML 文件路径（必需） |
+| `output` | 输出的 PPTX 文件路径（可选，默认为 `input.pptx`） |
+| `--template-dir` | 模板 YAML 文件所在目录 |
+| `--preview` | 启用浏览器预览模式（不生成 PPTX 文件） |
+| `--port` | 预览服务器端口（默认：随机 20000-30000） |
+
+## YAML 结构
+
+### 基本演示文稿

 ```yaml
-# presentation.yaml
 metadata:
-  title: "我的演示文稿"
-  size: "16:9"  # 16:9 或 4:3
+  size: 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. 自定义幻灯片
-
-```yaml
 slides:
  - background:
      color: "#ffffff"
    elements:
      - type: text
-        content: "自定义标题"
-        box: [1, 1, 8, 1]  # [x, y, width, height] 英寸
+        box: [1, 1, 8, 1]
+        content: "你好，世界！"
        font:
          size: 44
          bold: true
-          color: "#1a1a1a"
+          color: "#333333"
          align: center
-
-      - type: shape
-        shape: rectangle
-        box: [2, 3, 6, 2]
-        fill: "#4a90e2"
 ```

-## 📐 模板系统
+### 使用模板

-内置模板：
+```yaml
+metadata:
+  size: 16:9

- `title_slide`：标题页（主标题 + 副标题）
- `content_slide`：内容页（标题条 + 内容区）
- `two_column`：双栏布局
+slides:
+  - template: title-slide
+    vars:
+      title: "我的演示文稿"
+      subtitle: "yaml2pptx 简介"
+      author: "张三"

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

-### 文本元素
+## 元素类型
+
+### 文本

 ```yaml
 - type: text
-  content: "Hello World"
-  box: [x, y, width, height]
+  box: [x, y, width, height]  # 位置和尺寸（单位：英寸）
+  content: "文本内容"
  font:
-    size: 32
-    bold: true
-    italic: false
-    color: "#333333"
-    align: center  # left, center, right
+    size: 18              # 字号（磅）
+    bold: true/false      # 粗体
+    italic: true/false    # 斜体
+    color: "#ff0000"      # 颜色（#RGB 或 #RRGGBB）
+    align: left/center/right  # 对齐方式
 ```

-### 图片元素
+**文本自动换行**：文本框默认启用自动换行功能。当文字内容超过文本框宽度时，会自动换行显示，确保文字不会溢出边界。
+
+### 图片

 ```yaml
 - type: image
-  src: "images/logo.png"
  box: [x, y, width, height]
+  src: "path/to/image.png"  # 相对路径或绝对路径
 ```

-### 形状元素
+### 形状

 ```yaml
 - type: shape
-  shape: rectangle  # rectangle, ellipse, rounded_rectangle
  box: [x, y, width, height]
-  fill: "#4a90e2"
+  shape: rectangle/ellipse/rounded_rectangle
+  fill: "#4a90e2"           # 填充颜色
  line:
-    color: "#000000"
-    width: 2
+    color: "#000000"        # 边框颜色
+    width: 1                # 边框宽度（磅）
 ```

-### 表格元素
+### 表格

 ```yaml
 - type: table
-  position: [x, y]
-  col_widths: [2, 2, 2]  # 英寸
+  position: [x, y]          # 表格位置
+  col_widths: [2, 2, 2]     # 列宽（英寸）
  data:
-    - ["Header 1", "Header 2", "Header 3"]
-    - ["Cell 1", "Cell 2", "Cell 3"]
+    - ["表头1", "表头2", "表头3"]
+    - ["行1", "数据", "数据"]
+    - ["行2", "数据", "数据"]
  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
+模板允许你定义可复用的幻灯片布局，支持参数化。
+
+### 模板文件 (`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
 ```

-## 🔧 技术栈
+### 使用模板

- **Python 3.8+**
- **python-pptx**：PPTX 文件生成
- **PyYAML**：YAML 文件解析
- **uv**：Python 脚本运行器
-
-## 📝 示例
-
-查看 `examples/` 目录中的示例文件：
-
- `demo.yaml`：使用模板的完整示例（3页）
- `custom.yaml`：自定义幻灯片示例（2页）
- `complex.yaml`：**复杂综合示例（10页）** - 展示所有功能
-
-### 复杂示例亮点
-
-`complex.yaml` 是一个完整的商业计划演示文稿，包含：
-
-✨ **10个精心设计的幻灯片**：
-1. 封面页（使用 title_slide 模板）
-2. 议程页（自定义布局，包含时间轴）
-3. 公司概况（使用 content_slide 模板）
-4. 市场分析（使用 two_column 模板）
-5. 产品矩阵（复杂表格 + 架构图示）
-6. 财务预测（多个表格 + 数据可视化）
-7. 团队介绍（使用 two_column 模板）
-8. 竞争优势（视觉化卡片 + SWOT 表格）
-9. 产品路线图（使用 content_slide 模板）
-10. 结束页（自定义召唤行动页）
-
-🎨 **展示的功能**：
- ✅ 所有三种模板的使用
- ✅ 模板与自定义幻灯片混合
- ✅ 所有元素类型：文本、形状、表格
- ✅ 复杂布局和精确定位
- ✅ 多种形状类型和样式组合
- ✅ 丰富的颜色和字体样式（直接指定）
- ✅ 大量中文内容展示
- ✅ 表格的高级样式应用
- ✅ 视觉化信息展示（卡片、时间轴、架构图）
-
-```bash
-# 生成示例演示文稿
-uv run yaml2pptx.py examples/demo.yaml        # 基础示例
-uv run yaml2pptx.py examples/custom.yaml      # 自定义示例
-uv run yaml2pptx.py examples/complex.yaml     # 复杂综合示例 ⭐
+```yaml
+slides:
+  - template: title-slide
+    vars:
+      title: "我的演示文稿"
+      subtitle: "演示"
+      author: "李四"
 ```

-**生成的文件大小**：
- `demo_output.pptx` - 31KB
- `custom_output.pptx` - 29KB
- `complex_output.pptx` - 43KB (10页内容)
+### 模板变量说明

-## 🎓 YAML Schema 文档
+| 字段 | 说明 |
+|------|------|
+| `name` | 变量名（必需） |
+| `required` | 是否必需（默认：`false`） |
+| `default` | 默认值（未提供时使用） |

-详细的 YAML 格式说明，请参考各类型文件的示例和注释。
+### 条件渲染

-## 🚧 限制和已知问题
+使用 `visible` 属性控制元素的显示条件：

- 原型版本，仅支持核心功能
- 不支持复杂样式（渐变、阴影、动画等）
- 不支持 PPTX 到 YAML 的反向解析
- 图片背景功能暂未完整实现
+```yaml
+- type: text
+  content: "{subtitle}"
+  visible: "{subtitle != ''}"  # 仅当提供了 subtitle 时显示
+```

-## 📄 License
+## 背景设置
+
+幻灯片支持纯色背景：
+
+```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
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！