lanyuanxiaoyao
5d60f3c2c2
新增混合模式，允许幻灯片同时使用 template 和 elements，实现更灵活的布局组合。 核心变更： - core/presentation.py: 修改 render_slide() 支持三种模式（纯模板/纯自定义/混合模式） - 自定义元素可访问模板变量，实现主题色等值的统一控制 - 元素采用简单追加策略合并（模板元素在前，自定义元素在后） - 完全向后兼容现有用法 测试覆盖： - 新增 TestRenderSlideHybridMode 测试类，包含 8 个测试用例 - 验证向后兼容性（纯模板模式、纯自定义模式） - 验证混合模式功能（变量共享、空元素列表、元素顺序等） - 所有 79 个测试通过 文档更新： - README.md: 新增"混合模式模板"章节，包含语法示例和使用场景 - README_DEV.md: 更新开发文档，说明元素合并策略和实现细节 规范更新： - openspec/specs/template-system/spec.md: - 修改"系统必须支持自定义幻灯片"需求，支持混合模式 - 新增 4 个需求：变量共享、元素合并策略、向后兼容、内联模板支持 - 新增 13 个场景定义 归档： - openspec/changes/archive/2026-03-04-template-element-composition/: 完整变更记录
113 lines
4.9 KiB
Markdown
113 lines
4.9 KiB
Markdown
# Template System - Delta Spec
|
||
|
||
本文档是 template-system 能力的 delta spec，定义模板元素组合功能的变更。
|
||
|
||
## MODIFIED Requirements
|
||
|
||
### Requirement: 系统必须支持自定义幻灯片
|
||
|
||
系统 SHALL 支持不使用模板的自定义幻灯片，以及同时使用模板和自定义元素的混合模式幻灯片。
|
||
|
||
#### Scenario: 渲染自定义幻灯片
|
||
|
||
- **WHEN** 幻灯片未指定 `template` 字段，直接包含 `elements` 列表
|
||
- **THEN** 系统跳过模板渲染，直接处理元素列表
|
||
|
||
#### Scenario: 自定义幻灯片中直接指定样式
|
||
|
||
- **WHEN** 自定义幻灯片的元素直接指定 `color: "#4a90e2"`
|
||
- **THEN** 系统正确应用该颜色值
|
||
|
||
#### Scenario: 自定义幻灯片和模板混合使用
|
||
|
||
- **WHEN** 演示文稿中部分幻灯片使用模板，部分为自定义
|
||
- **THEN** 系统正确处理两种类型的幻灯片
|
||
|
||
#### Scenario: 混合模式幻灯片同时使用模板和自定义元素
|
||
|
||
- **WHEN** 幻灯片同时指定了 `template` 字段和 `elements` 列表
|
||
- **THEN** 系统先渲染模板获取模板元素列表，再追加自定义元素列表，生成最终的元素列表
|
||
|
||
#### Scenario: 混合模式中模板元素在前
|
||
|
||
- **WHEN** 幻灯片使用混合模式，模板元素和自定义元素位置重叠
|
||
- **THEN** 自定义元素在 z 轴上覆盖模板元素（后渲染在上层）
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 模板与自定义元素必须支持变量共享
|
||
|
||
系统 SHALL 允许自定义元素访问模板中定义的变量，实现主题色、布局参数等值的统一控制。
|
||
|
||
#### Scenario: 自定义元素使用模板变量
|
||
|
||
- **WHEN** 幻灯片使用 `template: content-slide`，提供 `vars: {theme_color: "#3949ab"}`，且自定义元素中定义 `fill: "{theme_color}"`
|
||
- **THEN** 系统将自定义元素中的 `{theme_color}` 替换为 `"#3949ab"`
|
||
|
||
#### Scenario: 自定义元素使用模板默认变量
|
||
|
||
- **WHEN** 模板定义了 `default: "#3949ab"` 的 `theme_color` 变量，幻灯片未提供该变量值，且自定义元素引用 `{theme_color}`
|
||
- **THEN** 系统使用模板的默认值 `"#3949ab"` 进行替换
|
||
|
||
#### Scenario: 自定义元素引用未定义变量时报错
|
||
|
||
- **WHEN** 自定义元素引用了 `{undefined_var}`，且该变量未在模板 vars 中定义，也未由幻灯片提供
|
||
- **THEN** 系统抛出错误，指出未定义的变量
|
||
|
||
### Requirement: 元素合并必须采用追加策略
|
||
|
||
系统 SHALL 使用简单追加策略合并模板元素和自定义元素，保持渲染顺序和 z 轴层级。
|
||
|
||
#### Scenario: 模板元素和自定义元素合并顺序
|
||
|
||
- **WHEN** 模板渲染后产生 2 个元素，幻灯片自定义元素列表包含 3 个元素
|
||
- **THEN** 最终元素列表包含 5 个元素，顺序为：模板元素1、模板元素2、自定义元素1、自定义元素2、自定义元素3
|
||
|
||
#### Scenario: 空自定义元素列表
|
||
|
||
- **WHEN** 幻灯片指定 `template` 和 `elements: []`（空数组）
|
||
- **THEN** 最终元素列表仅包含模板元素，等同于不指定 `elements` 字段
|
||
|
||
#### Scenario: 模板条件渲染后的元素合并
|
||
|
||
- **WHEN** 模板包含 3 个元素，其中 1 个因 `visible` 条件为假被过滤，幻灯片包含 2 个自定义元素
|
||
- **THEN** 最终元素列表包含 4 个元素：模板的 2 个可见元素，加上幻灯片的 2 个自定义元素
|
||
|
||
### Requirement: 混合模式必须保持向后兼容
|
||
|
||
系统 SHALL 在不使用混合模式时，保持与现有版本完全一致的行为。
|
||
|
||
#### Scenario: 仅使用模板时不指定 elements
|
||
|
||
- **WHEN** 幻灯片仅指定 `template` 字段，不包含 `elements` 字段
|
||
- **THEN** 系统表现与现有版本完全一致，仅渲染模板元素
|
||
|
||
#### Scenario: 仅使用自定义元素时不指定 template
|
||
|
||
- **WHEN** 幻灯片仅指定 `elements` 字段，不包含 `template` 字段
|
||
- **THEN** 系统表现与现有版本完全一致，仅渲染自定义元素
|
||
|
||
#### Scenario: 既不使用模板也不使用自定义元素
|
||
|
||
- **WHEN** 幻灯片既不指定 `template` 也不指定 `elements`
|
||
- **THEN** 系统生成空幻灯片（仅包含背景设置）
|
||
|
||
### Requirement: 混合模式必须支持内联模板
|
||
|
||
系统 SHALL 在混合模式中支持内联模板与外部模板，功能保持一致。
|
||
|
||
#### Scenario: 内联模板与自定义元素混合使用
|
||
|
||
- **WHEN** 幻灯片引用内联模板（在 YAML 文件的 `templates` 字段中定义），同时包含 `elements` 列表
|
||
- **THEN** 系统正确渲染内联模板元素，并追加自定义元素
|
||
|
||
#### Scenario: 外部模板与自定义元素混合使用
|
||
|
||
- **WHEN** 幻灯片引用外部模板（从 `--template-dir` 目录加载），同时包含 `elements` 列表
|
||
- **THEN** 系统正确加载外部模板，渲染模板元素，并追加自定义元素
|
||
|
||
#### Scenario: 内联和外部模板在同一演示文稿中混合使用
|
||
|
||
- **WHEN** 演示文稿同时定义了内联模板和使用外部模板，且部分幻灯片使用混合模式
|
||
- **THEN** 系统正确处理所有组合情况
|