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 字段时行为不变。
5.4 KiB
5.4 KiB
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 验证通过，元素在渲染时正常工作