feat: initial implementation of html2pptx with OpenSpec documentation
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
This commit is contained in:
174
openspec/specs/element-rendering/spec.md
Normal file
174
openspec/specs/element-rendering/spec.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Element Rendering
|
||||
|
||||
## Purpose
|
||||
|
||||
Element rendering系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 PPTX 文档中的实际对象。它处理元素的定位、样式应用、层次管理，以及幻灯片背景设置。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须支持文本元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框。
|
||||
|
||||
#### Scenario: 渲染基本文本元素
|
||||
|
||||
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
|
||||
- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello"
|
||||
|
||||
#### Scenario: 应用文本字体样式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
|
||||
- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333
|
||||
|
||||
#### Scenario: 应用文本对齐方式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {align: center}`
|
||||
- **THEN** 系统将文本设置为居中对齐
|
||||
|
||||
#### Scenario: 支持多种对齐方式
|
||||
|
||||
- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一
|
||||
- **THEN** 系统正确应用对应的对齐方式
|
||||
|
||||
### Requirement: 系统必须支持图片元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象。
|
||||
|
||||
#### Scenario: 渲染本地图片
|
||||
|
||||
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
|
||||
- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小
|
||||
|
||||
#### Scenario: 图片文件不存在时报错
|
||||
|
||||
- **WHEN** 图片 src 指向不存在的文件路径
|
||||
- **THEN** 系统抛出错误，明确指出图片文件未找到
|
||||
|
||||
#### Scenario: 图片格式不支持时报错
|
||||
|
||||
- **WHEN** 图片文件格式不被 python-pptx 支持
|
||||
- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式
|
||||
|
||||
#### Scenario: 相对路径处理
|
||||
|
||||
- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"`
|
||||
- **THEN** 系统基于演示文稿文件所在目录解析相对路径
|
||||
|
||||
### Requirement: 系统必须支持形状元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的形状元素渲染为 PPTX 形状对象。
|
||||
|
||||
#### Scenario: 渲染矩形形状
|
||||
|
||||
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 3×1 英寸的矩形，填充颜色为 #4a90e2
|
||||
|
||||
#### Scenario: 渲染圆形形状
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `ellipse`
|
||||
- **THEN** 系统渲染椭圆/圆形形状
|
||||
|
||||
#### Scenario: 渲染圆角矩形
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle`
|
||||
- **THEN** 系统渲染圆角矩形形状
|
||||
|
||||
#### Scenario: 应用形状边框样式
|
||||
|
||||
- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}`
|
||||
- **THEN** 系统为形状添加黑色、2pt 宽度的边框
|
||||
|
||||
### Requirement: 系统必须支持表格元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的表格元素渲染为 PPTX 表格对象。
|
||||
|
||||
#### Scenario: 渲染基本表格
|
||||
|
||||
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 2×2 表格，列宽各为 2 英寸
|
||||
|
||||
#### Scenario: 应用表格样式
|
||||
|
||||
- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}`
|
||||
- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色
|
||||
|
||||
#### Scenario: 表格数据为空时报错
|
||||
|
||||
- **WHEN** 表格的 `data` 字段为空数组
|
||||
- **THEN** 系统抛出错误，提示表格数据不能为空
|
||||
|
||||
#### Scenario: 表格列宽不匹配时报错
|
||||
|
||||
- **WHEN** `col_widths` 数组长度与表格列数不一致
|
||||
- **THEN** 系统抛出错误，要求列宽数量与列数匹配
|
||||
|
||||
### Requirement: 元素位置必须使用英寸单位
|
||||
|
||||
系统 SHALL 将元素的 box 或 position 字段中的数值解释为英寸单位。
|
||||
|
||||
#### Scenario: box 数组表示位置和尺寸
|
||||
|
||||
- **WHEN** 元素定义了 `box: [1, 2, 8, 3]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸, width=8英寸, height=3英寸
|
||||
|
||||
#### Scenario: position 数组表示位置
|
||||
|
||||
- **WHEN** 表格元素定义了 `position: [1, 2]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸
|
||||
|
||||
#### Scenario: 负数坐标值报错
|
||||
|
||||
- **WHEN** box 或 position 包含负数值
|
||||
- **THEN** 系统抛出错误，要求坐标值必须为非负数
|
||||
|
||||
### Requirement: 系统必须支持幻灯片背景设置
|
||||
|
||||
系统 SHALL 支持为幻灯片设置纯色背景或图片背景。
|
||||
|
||||
#### Scenario: 设置纯色背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}`
|
||||
- **THEN** 系统将幻灯片背景设置为白色
|
||||
|
||||
#### Scenario: 设置图片背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {image: "bg.png"}`
|
||||
- **THEN** 系统使用指定图片作为幻灯片背景
|
||||
|
||||
#### Scenario: 背景图片不存在时报错
|
||||
|
||||
- **WHEN** 背景图片路径不存在
|
||||
- **THEN** 系统抛出错误，提示背景图片文件未找到
|
||||
|
||||
### Requirement: 系统必须处理元素重叠和层次
|
||||
|
||||
系统 SHALL 按照元素在 elements 列表中的顺序渲染，后定义的元素显示在前面元素之上。
|
||||
|
||||
#### Scenario: 元素按定义顺序渲染
|
||||
|
||||
- **WHEN** elements 列表为 `[shape1, text1, image1]`
|
||||
- **THEN** 系统先渲染 shape1，再渲染 text1，最后渲染 image1（image1 在最上层）
|
||||
|
||||
#### Scenario: 重叠元素的显示层次
|
||||
|
||||
- **WHEN** 两个元素的位置有重叠
|
||||
- **THEN** 后定义的元素遮盖先定义的元素
|
||||
|
||||
### Requirement: 系统必须验证元素类型
|
||||
|
||||
系统 SHALL 验证每个元素的 type 字段，仅支持已定义的元素类型。
|
||||
|
||||
#### Scenario: 支持的元素类型
|
||||
|
||||
- **WHEN** 元素的 `type` 为 `text`、`image`、`shape`、`table` 之一
|
||||
- **THEN** 系统正常渲染该元素
|
||||
|
||||
#### Scenario: 不支持的元素类型报错
|
||||
|
||||
- **WHEN** 元素的 `type` 为未定义的值（如 "video"）
|
||||
- **THEN** 系统抛出错误，提示不支持该元素类型，并列出支持的类型
|
||||
|
||||
#### Scenario: 缺少 type 字段报错
|
||||
|
||||
- **WHEN** 元素未定义 `type` 字段
|
||||
- **THEN** 系统抛出错误，要求每个元素必须包含 type 字段
|
||||
Reference in New Issue
Block a user