1
0

feat: 为metadata、模板和幻灯片添加description字段支持

添加可选的description字段用于文档目的,不影响渲染输出。

主要更改:
- core/presentation.py: 添加metadata.description属性
- core/template.py: 添加template.description属性
- tests: 添加16个新测试用例验证description功能
- docs: 更新README.md和README_DEV.md文档
- specs: 新增page-description规范文件
This commit is contained in:
2026-03-04 13:22:33 +08:00
parent 5d60f3c2c2
commit 2fd8bc1b4a
12 changed files with 845 additions and 0 deletions

View File

@@ -595,6 +595,48 @@ if right > slide_width + TOLERANCE:
- 检查变量定义是否有必需的 `name` 字段
- 检测默认值中引用不存在的变量
### 8. description 字段
**决策**:为 metadata、模板和幻灯片添加可选的 `description` 字段
**理由**
- 自文档化:提高模板和演示文稿的可读性和可维护性
- 不影响渲染description 仅用于文档目的,不参与 PPTX 生成
- 完全向后兼容:字段为可选,现有文件无需修改
**实现要点**
1. **数据模型**
- `Presentation.description`:从 `metadata.description` 读取
- `Template.description`:从模板文件的 `description` 字段读取
- `Slide.description`:在 `render_slide()` 返回值中保留
2. **YAML 解析**
- 使用 `.get('description')` 自动处理缺失情况(返回 None
- YAML 原生支持多行文本格式
3. **不参与渲染**
- description 字段不传递给渲染器
- 不写入最终的 PPTX 文件
**示例**
```yaml
# metadata description
metadata:
description: "2024年度项目进展总结"
# 模板 description
templates:
title-slide:
description: "用于章节标题页的模板"
elements: [...]
# 幻灯片 description
slides:
- description: "介绍项目背景"
template: title-slide
```
## 扩展指南
### 添加新元素类型