lanyuanxiaoyao
2fd8bc1b4a
添加可选的description字段用于文档目的，不影响渲染输出。 主要更改： - core/presentation.py: 添加metadata.description属性 - core/template.py: 添加template.description属性 - tests: 添加16个新测试用例验证description功能 - docs: 更新README.md和README_DEV.md文档 - specs: 新增page-description规范文件
37 lines
1.6 KiB
Markdown
37 lines
1.6 KiB
Markdown
# Proposal: Add Description Field to Pages and Slides
|
||
|
||
## Why
|
||
|
||
当前项目和模板系统中缺乏对文档、页面和幻灯片用途的内置说明机制。当用户或开发者查看演示文稿YAML时，难以快速理解整个文档的概要、某个模板的设计意图或幻灯片的使用场景。添加description字段可以提供自文档化的能力，提高演示文稿、模板和幻灯片的可维护性和可读性。
|
||
|
||
## What Changes
|
||
|
||
- 为metadata添加可选的 `description` 字段，用于描述整个演示文稿的概要和用途
|
||
- 为模板文件添加可选的 `description` 字段，用于说明该模板的用途和设计意图
|
||
- 为幻灯片定义添加可选的 `description` 字段，用于说明该幻灯片的作用和内容
|
||
- description字段为纯文本字符串，完全可选，不影响现有渲染逻辑
|
||
- 保留description字段以供工具和文档生成使用
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
- `page-description`: 为模板页面和幻灯片添加描述字段的功能
|
||
|
||
### Modified Capabilities
|
||
无现有能力的需求变更，仅新增可选字段
|
||
|
||
## Impact
|
||
|
||
**受影响的代码模块:**
|
||
- `models/` - 元数据、模板和幻灯片数据模型需要支持description字段
|
||
- `yaml_parsing/` - YAML解析器需要读取metadata和模板、幻灯片的description字段
|
||
- `specs/` - 新增page-description规范文档
|
||
|
||
**不受影响的模块:**
|
||
- 渲染逻辑 - description字段不影响视觉渲染
|
||
- 输出PPTX - description不写入最终的PPTX文件
|
||
|
||
**向后兼容性:**
|
||
- 完全向后兼容，description为可选字段
|
||
- 现有模板和YAML文件无需修改即可继续使用
|