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 变更
76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
## 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 以反映新行为
|