1
0

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 变更
This commit is contained in:
2026-03-04 14:47:03 +08:00
parent f34405be36
commit 7ef29ea039
12 changed files with 454 additions and 15 deletions

View File

@@ -545,40 +545,48 @@ if right > slide_width + TOLERANCE:
**理由**
- 自文档化:提高模板和演示文稿的可读性和可维护性
- 不影响渲染:description 仅用于文档目的,不参与 PPTX 生成
- 备注支持:幻灯片 description 会写入 PPT 备注页,方便演讲者查看
- 完全向后兼容:字段为可选,现有文件无需修改
**实现要点**
1. **数据模型**
- `Presentation.description`:从 `metadata.description` 读取
- `Template.description`:从模板文件的 `description` 字段读取
- `Slide.description`:在 `render_slide()` 返回值中保留
- `Presentation.description`:从 `metadata.description` 读取,用于描述整个演示文稿
- `Template.description`:从模板文件的 `description` 字段读取,描述模板用途
- `Slide.description`:在 `render_slide()` 返回值中保留,会写入 PPT 备注页
2. **YAML 解析**
- 使用 `.get('description')` 自动处理缺失情况(返回 None
- YAML 原生支持多行文本格式
3. **不参与渲染**
- description 字段不传递给渲染器
- 不写入最终的 PPTX 文件
3. **PPT 备注功能**
- 仅幻灯片级别的 `description` 会写入 PPT 备注页
- 模板的 `description` 不继承到幻灯片备注
- `metadata.description` 不写入单个幻灯片备注
- 如果幻灯片没有 `description`,则不设置备注
4. **渲染实现**
- `PptxGenerator._set_notes()`:设置幻灯片备注的私有方法
- `PptxGenerator.add_slide()`:调用 `_set_notes()` 设置备注
**示例**
```yaml
# metadata description
# metadata description - 描述整个演示文稿
metadata:
description: "2024年度项目进展总结"
# 模板 description
# 模板 description - 描述模板用途
templates:
title-slide:
description: "用于章节标题页的模板"
elements: [...]
# 幻灯片 description
# 幻灯片 description - 写入 PPT 备注页
slides:
- description: "介绍项目背景"
- description: "介绍项目背景和目标,包含以下要点:..."
template: title-slide
vars:
title: "项目背景"
```
## 扩展指南