PPTX/openspec/changes/archive/2026-03-04-add-slide-notes/design.md at 7ef29ea03945af87f54338ec91142f6d3cd1d882

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

2.6 KiB

Raw Blame History

Context

当前系统中，description 字段已在以下位置被解析：

core/presentation.py: 演示文稿级别的 metadata.description
core/template.py: 模板级别的 template.description
core/presentation.py: 幻灯片级别的 slide.description 在 render_slide 方法返回值中

然而，PPTX 渲染器 (renderers/pptx_renderer.py) 的 add_slide 方法只处理 background 和 elements，完全忽略了 description 字段。

python-pptx 库原生支持备注功能，通过 slide.notes_slide.notes_text_frame.text 即可设置。

Goals / Non-Goals

Goals:

将幻灯片的 description 字段写入 PPT 备注页
仅处理幻灯片级别的 description，不涉及模板或演示文稿级别的 description
保持向后兼容，没有 description 时不设置备注

Non-Goals:

不实现富文本备注（仅支持纯文本）
不合并模板的 description
不处理演示文稿级别的 metadata.description

Decisions

1. 备注内容来源

决策: 仅使用幻灯片自己的 description 字段

理由:

幻灯片 description 是用户针对具体页面编写的说明
模板 description 描述的是模板用途，不适合作为单个幻灯片的备注
避免复杂的合并逻辑，保持简单清晰

考虑的替代方案:

合并模板 description 和幻灯片 description → 过于复杂，可能产生冗余内容
仅在没有幻灯片 description 时使用模板 description → 增加认知负担

2. 无 description 时的行为

决策: 不设置备注，保持备注页为空

理由:

python-pptx 默认创建空备注页
不需要额外判断或清理操作
保持行为可预测

3. 代码位置

决策: 在 PptxGenerator 类中添加私有方法 _set_notes

理由:

与现有的 _render_background、_render_element 等方法保持一致
封装备注设置逻辑，便于测试和维护
不影响 add_slide 方法的主流程

Risks / Trade-offs

Risk: 长文本可能导致备注溢出

影响: description 内容过长时，可能在备注页中显示不佳

缓解: python-pptx 会自动处理文本换行，这是库的默认行为，无需额外处理

Trade-off: 仅支持纯文本

限制: python-pptx 的备注不支持富文本格式（加粗、颜色等）

权衡: 备注的主要用途是演讲者参考，纯文本已满足需求；富文本支持需要更复杂的实现，收益不大

Risk: 现有 spec 需要更新

影响: page-description spec 明确规定 "description不写入PPTX文件"

缓解: 这正是本次变更的目的，需要更新该 spec 以反映新行为

2.6 KiB Raw Blame History Unescape Escape