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 字段时行为不变。
42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
## Why
|
||
|
||
当前外部模板系统虽然功能完整，但需要单独管理模板文件，使用门槛较高。项目中没有任何实际使用的案例，说明用户体验有待改善。通过支持在 YAML 源文件中内联定义模板，可以在不需要跨文档复用的情况下，大幅简化单文档的编写流程，提升开发效率。
|
||
|
||
## What Changes
|
||
|
||
- 在 YAML 文件中新增 `templates` 字段，允许在源文件中定义模板
|
||
- 修改 `Presentation.get_template()` 方法，支持内联模板和外部模板的查找，内联模板优先
|
||
- 在 `Template` 类中新增 `from_data()` 类方法，支持从字典创建模板实例
|
||
- 在 `yaml_loader` 中新增 `validate_templates_yaml()` 函数，验证 templates 字段结构
|
||
- 修改现有模板验证逻辑，支持内联模板和外部模板共存
|
||
- 添加完整的错误处理机制，包括模板定义错误、引用错误、变量传递错误和循环引用检测
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `inline-templates`: 支持 YAML 源文件中定义和使用内联模板，包括模板定义、变量替换、条件渲染等功能
|
||
|
||
### Modified Capabilities
|
||
|
||
无。此变更为新增功能，不修改现有功能的需求行为。
|
||
|
||
## Impact
|
||
|
||
**受影响的代码模块**:
|
||
- `core/presentation.py`: 修改 `__init__` 保存 templates 字段，修改 `get_template()` 支持内联模板查找
|
||
- `core/template.py`: 新增 `from_data()` 类方法，支持从字典创建模板
|
||
- `loaders/yaml_loader.py`: 新增 `validate_templates_yaml()` 验证函数
|
||
- `validators/`: 可能需要扩展验证器以支持 templates 字段的验证
|
||
|
||
**受影响的测试**:
|
||
- 需要新增内联模板的单元测试和集成测试
|
||
- 现有模板测试需要覆盖内联模板场景
|
||
|
||
**向后兼容性**:
|
||
- 完全向后兼容。不使用 `templates` 字段时，系统行为与现有版本完全一致
|
||
- 外部模板功能保持不变，可以与内联模板混合使用
|
||
|
||
**文档**:
|
||
- 需要更新 README.md 和 README_DEV.md，说明内联模板的语法和使用方法
|