lanyuanxiaoyao
01eacb0b97
支持在 YAML 源文件中直接定义模板，无需单独的模板文件。 简化单文档编写流程，降低模板系统使用门槛。 核心功能： - 在 YAML 顶层新增 templates 字段定义内联模板 - 支持变量替换、条件渲染、默认值等完整模板功能 - 内联模板优先于外部模板查找 - 同名冲突检测：禁止内联和外部模板同名 - 相互引用检测：禁止内联模板之间相互引用 - 完整的错误处理和验证机制 代码变更： - core/template.py: 新增 from_data() 类方法 - core/presentation.py: 支持内联模板查找和冲突检测 - loaders/yaml_loader.py: 新增 validate_templates_yaml() 验证 - validators/: 扩展验证器支持内联模板 测试： - 新增 9 个内联模板专项测试 - 修复 1 个变量验证测试 - 所有 333 个测试通过 文档： - README.md: 添加内联模板使用指南和最佳实践 - README_DEV.md: 说明实现细节和设计决策 完全向后兼容，不使用 templates 字段时行为不变。
113 lines
5.4 KiB
Markdown
113 lines
5.4 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: YAML 文件支持内联模板定义
|
|
|
|
系统 SHALL 允许用户在 YAML 源文件的 `templates` 字段中定义内联模板，模板定义包括变量和元素。
|
|
|
|
#### Scenario: 定义简单的内联模板
|
|
- **WHEN** 用户在 YAML 文件的 `templates` 字段中定义一个名为 `title-slide` 的模板，包含 `vars` 和 `elements` 字段
|
|
- **THEN** 系统 SHALL 成功解析模板定义，并将模板存储在 `inline_templates` 字典中
|
|
|
|
#### Scenario: 定义多个内联模板
|
|
- **WHEN** 用户在 YAML 文件的 `templates` 字段中定义多个不同的内联模板
|
|
- **THEN** 系统 SHALL 成功解析所有模板定义，并允许通过模板名称引用任何一个模板
|
|
|
|
### Requirement: 内联模板支持变量替换
|
|
|
|
系统 SHALL 支持在内联模板的元素中使用 `{variable}` 语法定义变量占位符，并在渲染时替换为实际值。
|
|
|
|
#### Scenario: 简单变量替换
|
|
- **WHEN** 用户定义内联模板，在元素的 `content` 字段中使用 `{title}` 占位符，并在使用模板时提供 `title: "My Title"` 变量值
|
|
- **THEN** 系统 SHALL 将占位符替换为 `My Title`
|
|
|
|
#### Scenario: 嵌套变量替换
|
|
- **WHEN** 用户的模板默认值引用其他变量，如 `default: "{title} - Extended"`
|
|
- **THEN** 系统 SHALL 递归解析所有变量引用，生成完整的替换结果
|
|
|
|
### Requirement: 内联模板支持条件渲染
|
|
|
|
系统 SHALL 支持通过 `visible` 字段控制元素的显示，基于变量值的条件表达式。
|
|
|
|
#### Scenario: 条件渲染为真
|
|
- **WHEN** 元素的 `visible` 字段设置为 `"{subtitle != ''}"`，且用户提供非空的 `subtitle` 值
|
|
- **THEN** 系统 SHALL 在渲染结果中包含该元素
|
|
|
|
#### Scenario: 条件渲染为假
|
|
- **WHEN** 元素的 `visible` 字段设置为 `"{subtitle != ''}"`，且用户提供空的 `subtitle` 值
|
|
- **THEN** 系统 SHALL 在渲染结果中排除该元素
|
|
|
|
### Requirement: 内联模板支持变量默认值
|
|
|
|
系统 SHALL 支持在模板的 `vars` 定义中为可选变量提供 `default` 值。
|
|
|
|
#### Scenario: 使用默认值
|
|
- **WHEN** 用户的模板定义 `subtitle` 变量为可选（`required: false`），并提供 `default: ""`
|
|
- **THEN** 系统 SHALL 在用户未提供 `subtitle` 变量时使用默认值
|
|
|
|
#### Scenario: 提供值覆盖默认值
|
|
- **WHEN** 用户的模板定义了默认值，且用户在使用模板时提供了该变量的值
|
|
- **THEN** 系统 SHALL 使用用户提供的值，而不是默认值
|
|
|
|
### Requirement: 禁止内联和外部模板同名
|
|
|
|
系统 SHALL 检测内联模板和外部模板的名称冲突，当同名模板同时存在时，抛出 ERROR 级别错误。
|
|
|
|
#### Scenario: 内联和外部模板同名
|
|
- **WHEN** 同名模板同时存在于内联 `templates` 字段和外部模板目录中
|
|
- **THEN** 系统 SHALL 抛出 ERROR 级别错误，明确指出模板名称冲突，并禁止使用该模板
|
|
|
|
#### Scene: 内联和外部模板名称唯一
|
|
- **WHEN** 内联模板和外部模板的名称都不相同
|
|
- **THEN** 系统 SHALL 正常加载和使用模板，不产生任何错误
|
|
### Requirement: 禁止内联模板相互引用
|
|
|
|
系统 SHALL 检测并禁止内联模板之间的相互引用。
|
|
|
|
#### Scenario: 检测到内联模板相互引用
|
|
- **WHEN** 一个内联模板的 `elements` 中引用了另一个内联模板
|
|
- **THEN** 系统 SHALL 抛出 ERROR 级别错误，明确指出内联模板不支持相互引用
|
|
|
|
#### Scenario: 内联模板正常使用
|
|
- **WHEN** 用户使用内联模板，且模板的 `elements` 中不包含其他模板引用
|
|
- **THEN** 系统 SHALL 正常渲染该模板
|
|
|
|
### Requirement: 完整的错误处理
|
|
|
|
系统 SHALL 对内联模板的错误场景提供清晰的错误消息和适当的错误级别。
|
|
|
|
#### Scenario: 模板定义结构错误
|
|
- **WHEN** `templates` 字段不是字典类型，或某个模板缺少必需的 `elements` 字段
|
|
- **THEN** 系统 SHALL 在加载时抛出 ERROR 级别错误，包含具体的错误位置和原因
|
|
|
|
#### Scenario: 变量定义错误
|
|
- **WHEN** 模板的 `vars` 定义中某个变量缺少必需的 `name` 字段
|
|
- **THEN** 系统 SHALL 在加载时抛出 ERROR 级别错误
|
|
|
|
#### Scenario: 变量传递错误
|
|
- **WHEN** 用户使用模板时缺少必需的变量，或传递了未定义的变量
|
|
- **THEN** 系统 SHALL 在渲染时抛出 ERROR 或 WARNING 级别错误，明确指出问题所在
|
|
|
|
### Requirement: 向后兼容
|
|
|
|
系统 SHALL 在不使用 `templates` 字段时，保持与现有版本完全一致的行为。
|
|
|
|
#### Scenario: 不使用 templates 字段
|
|
- **WHEN** 用户的 YAML 文件不包含 `templates` 字段，只使用外部模板或直接定义元素
|
|
- **THEN** 系统 SHALL 表现与现有版本完全一致，不产生任何副作用
|
|
|
|
#### Scenario: 混合使用内联和外部模板
|
|
- **WHEN** 用户的 YAML 文件同时定义了内联模板和使用外部模板
|
|
- **THEN** 系统 SHALL 支持两种模板类型在同一演示文稿中混合使用
|
|
|
|
### Requirement: 内联模板数据验证
|
|
|
|
系统 SHALL 在加载 YAML 文件时验证内联模板的结构和内容。
|
|
|
|
#### Scenario: 验证模板结构
|
|
- **WHEN** 用户定义的内联模板包含 `vars` 和 `elements` 字段，且结构正确
|
|
- **THEN** 系统 SHALL 验证通过，允许后续使用该模板
|
|
|
|
#### Scenario: 验证元素结构
|
|
- **WHEN** 用户的内联模板 `elements` 中定义了有效的元素类型和字段
|
|
- **THEN** 系统 SHALL 验证通过，元素在渲染时正常工作
|