lanyuanxiaoyao
7ef29ea039
- 添加 PptxGenerator._set_notes() 方法设置备注 - 在 add_slide() 中调用 _set_notes() 处理 description - 仅幻灯片级别的 description 写入备注，不继承模板 - 添加备注功能测试用例（8个测试） - 更新 README.md 和 README_DEV.md 文档 - 新建 pptx-slide-notes spec - 更新 page-description spec 允许写入备注 - 归档 add-slide-notes 变更
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# Page Description
|
||
|
||
## Purpose
|
||
|
||
Page Description功能允许用户为文档元数据、模板和幻灯片添加描述信息，用于说明文档概要、页面的用途、设计意图或内容概要。这提高了演示文稿、模板和幻灯片的可读性和可维护性。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: metadata必须支持可选的description字段
|
||
|
||
演示文稿的metadata SHALL 支持可选的 `description` 字段，用于描述整个演示文稿的概要和用途。
|
||
|
||
#### Scenario: metadata包含description字段
|
||
|
||
- **WHEN** YAML文件的metadata定义了 `description: "这是关于项目年度总结的演示文稿"`
|
||
- **THEN** 系统成功加载该描述字段，可通过metadata对象访问
|
||
|
||
#### Scenario: metadata不包含description字段
|
||
|
||
- **WHEN** YAML文件的metadata未定义 `description` 字段
|
||
- **THEN** 系统正常加载演示文稿，description属性为None或空字符串
|
||
|
||
#### Scenario: metadata description为空字符串
|
||
|
||
- **WHEN** metadata定义了 `description: ""`
|
||
- **THEN** 系统接受空字符串作为有效值
|
||
|
||
### Requirement: 模板必须支持可选的description字段
|
||
|
||
模板 SHALL 支持可选的 `description` 字段，用于描述该模板的用途和设计意图。
|
||
|
||
#### Scenario: 模板包含description字段
|
||
|
||
- **WHEN** 模板文件定义了 `description: "用于章节标题页的模板，包含主标题和副标题"`
|
||
- **THEN** 系统成功加载该描述字段，可通过模板对象访问
|
||
|
||
#### Scenario: 模板不包含description字段
|
||
|
||
- **WHEN** 模板文件未定义 `description` 字段
|
||
- **THEN** 系统正常加载模板，description属性为None或空字符串
|
||
|
||
#### Scenario: description为空字符串
|
||
|
||
- **WHEN** 模板文件定义了 `description: ""`
|
||
- **THEN** 系统接受空字符串作为有效值
|
||
|
||
### Requirement: 幻灯片必须支持可选的description字段
|
||
|
||
幻灯片定义 SHALL 支持可选的 `description` 字段，用于描述该幻灯片的作用和内容。
|
||
|
||
#### Scenario: 幻灯片包含description字段
|
||
|
||
- **WHEN** 幻灯片定义了 `description: "介绍项目背景和目标"`
|
||
- **THEN** 系统成功加载该描述字段，可通过幻灯片对象访问
|
||
|
||
#### Scenario: 幻灯片不包含description字段
|
||
|
||
- **WHEN** 幻灯片定义未包含 `description` 字段
|
||
- **THEN** 系统正常处理幻灯片，description属性为None或空字符串
|
||
|
||
### Requirement: description字段不得影响渲染逻辑
|
||
|
||
系统 SHALL 在渲染幻灯片时忽略 `description` 字段对视觉元素的影响，但会将幻灯片级别的 `description` 写入 PPTX 备注页。
|
||
|
||
#### Scenario: 渲染包含description的模板
|
||
|
||
- **WHEN** 系统渲染包含 `description` 字段的模板
|
||
- **THEN** description不参与元素渲染，不影响幻灯片视觉输出
|
||
|
||
#### Scenario: 渲染包含description的幻灯片
|
||
|
||
- **WHEN** 系统渲染包含 `description` 字段的幻灯片
|
||
- **THEN** description写入PPTX文件的备注页，不影响幻灯片视觉输出
|
||
|
||
### Requirement: YAML解析器必须正确解析description字段
|
||
|
||
系统 SHALL 从YAML文件中正确读取 `description` 字段，并将其传递给数据模型。
|
||
|
||
#### Scenario: 解析metadata中的description
|
||
|
||
- **WHEN** YAML文件的metadata包含 `description: "文档描述"`
|
||
- **THEN** 解析器将该字符串传递给metadata对象的description属性
|
||
|
||
#### Scenario: 解析模板中的description
|
||
|
||
- **WHEN** YAML文件中的模板包含 `description: "这是描述"`
|
||
- **THEN** 解析器将该字符串传递给模板对象的description属性
|
||
|
||
#### Scenario: 解析幻灯片中的description
|
||
|
||
- **WHEN** YAML文件中的幻灯片包含 `description: "幻灯片描述"`
|
||
- **THEN** 解析器将该字符串传递给幻灯片对象的description属性
|
||
|
||
### Requirement: 数据模型必须包含description属性
|
||
|
||
元数据、模板和幻灯片数据模型 SHALL 包含 `description` 属性，用于存储描述信息。
|
||
|
||
#### Scenario: metadata对象包含description属性
|
||
|
||
- **WHEN** 开发者访问metadata对象
|
||
- **THEN** 可以通过 `metadata.description` 获取描述信息
|
||
|
||
#### Scenario: 模板对象包含description属性
|
||
|
||
- **WHEN** 开发者访问模板对象
|
||
- **THEN** 可以通过 `template.description` 获取描述信息
|
||
|
||
#### Scenario: 幻灯片对象包含description属性
|
||
|
||
- **WHEN** 开发者访问幻灯片对象
|
||
- **THEN** 可以通过 `slide.description` 获取描述信息
|
||
|
||
### Requirement: description字段必须支持中文字符
|
||
|
||
系统 SHALL 支持在 `description` 字段中使用中文字符和其他Unicode字符。
|
||
|
||
#### Scenario: metadata description包含中文
|
||
|
||
- **WHEN** metadata的description包含中文字符，如 "这是关于项目的演示文稿"
|
||
- **THEN** 系统正确处理，不出现编码错误
|
||
|
||
#### Scenario: description包含中文
|
||
|
||
- **WHEN** 模板或幻灯片的description包含中文字符，如 "这是中文描述"
|
||
- **THEN** 系统正确处理，不出现编码错误
|
||
|
||
#### Scenario: description包含多行文本
|
||
|
||
- **WHEN** description字段使用YAML多行文本格式
|
||
- **THEN** 系统正确读取完整的描述内容
|