Files

lanyuanxiaoyao 7ef29ea039 feat: 实现幻灯片备注功能，将description写入PPT备注页

- 添加 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 变更

2026-03-04 14:47:03 +08:00

4.9 KiB

Raw Permalink Blame History

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 系统正确读取完整的描述内容

4.9 KiB Raw Permalink Blame History Unescape Escape