1
0

feat: 实现模板元素混合模式功能

新增混合模式,允许幻灯片同时使用 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/: 完整变更记录
This commit is contained in:
2026-03-04 13:12:51 +08:00
parent 5b367f7ef3
commit 5d60f3c2c2
10 changed files with 1042 additions and 21 deletions

View File

@@ -139,7 +139,7 @@ Template system 提供可复用的幻灯片布局和样式定义。模板包含
### Requirement: 系统必须支持自定义幻灯片
系统 SHALL 支持不使用模板,直接定义元素的自定义幻灯片。
系统 SHALL 支持不使用模板的自定义幻灯片,以及同时使用模板和自定义元素的混合模式幻灯片。
#### Scenario: 渲染自定义幻灯片
@@ -156,6 +156,16 @@ Template system 提供可复用的幻灯片布局和样式定义。模板包含
- **WHEN** 演示文稿中部分幻灯片使用模板,部分为自定义
- **THEN** 系统正确处理两种类型的幻灯片
#### Scenario: 混合模式幻灯片同时使用模板和自定义元素
- **WHEN** 幻灯片同时指定了 `template` 字段和 `elements` 列表
- **THEN** 系统先渲染模板获取模板元素列表,再追加自定义元素列表,生成最终的元素列表
#### Scenario: 混合模式中模板元素在前
- **WHEN** 幻灯片使用混合模式,模板元素和自定义元素位置重叠
- **THEN** 自定义元素在 z 轴上覆盖模板元素(后渲染在上层)
### Requirement: 模板变量解析必须深度递归
系统 SHALL 递归解析模板元素的所有嵌套字段中的变量引用。
@@ -241,3 +251,79 @@ Template system 提供可复用的幻灯片布局和样式定义。模板包含
- **WHEN** 自定义幻灯片(不使用模板)定义了 `enabled: false`
- **THEN** 系统跳过该幻灯片,不渲染元素列表
### 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** 系统正确处理所有组合情况