1
0

refactor: 重构外部模板系统,改为单文件模板库模式

主要变更:
- 将 templates_dir 参数改为 template_file,支持单个模板库 YAML 文件
- 添加模板库 YAML 验证功能
- 为模板添加 base_dir 支持,正确解析相对路径资源
- 内联模板与外部模板同名时改为警告(内联优先)
- 移除模板缓存机制,直接使用模板库字典
- 更新所有相关测试以适配新的模板加载方式

此重构简化了模板管理,使模板资源的路径解析更加清晰明确。
This commit is contained in:
2026-03-05 13:26:29 +08:00
parent bd12fce14b
commit f1aae96a04
27 changed files with 2141 additions and 1988 deletions

View File

@@ -0,0 +1,83 @@
## Why
当前外部模板系统使用文件夹+文件名的方式存储和查询模板,与内联模板的字典查询方式不一致。这种不一致导致以下问题:
1. 模板名称受文件命名规则限制(不能包含路径分隔符)
2. 查询逻辑不统一(外部模板通过文件系统查找,内联模板通过字典键查找)
3. 外部模板分散在多个文件中,难以管理和分发
重构为统一的模板库格式后,外部模板和内联模板将使用相同的数据结构和查询逻辑,提高系统一致性。
## What Changes
- **BREAKING**: 命令行参数 `--template-dir` 改为 `--template`,指定单个 YAML 文件而非文件夹
- **BREAKING**: 外部模板文件格式从单个模板的 YAML 改为包含多个模板的模板库 YAML
- 移除外部模板的缓存机制 (`template_cache`)
- 统一资源路径解析:所有图片元素的相对路径在渲染前都解析为绝对路径
- 自定义元素和内联模板元素:相对于文档 YAML 所在目录
- 外部模板元素:相对于模板库文件所在目录
- 模板库文件支持元数据字段description、version、author 等)
- 优化错误提示:区分模板库文件不存在、模板名称不存在两种错误
- 同名冲突处理:内联和外部模板同名时发出 WARNING优先使用内联模板
## Capabilities
### New Capabilities
- `template-library`: 模板库文件的加载、验证和管理
- 模板库文件必须包含 `templates` 字段(字典类型)
- 支持元数据字段description、version、author
- 递归验证每个模板的结构vars、elements
- 提供模板库文件级别的错误提示
### Modified Capabilities
- `template-system`: 模板查询和引用逻辑
- 外部模板查询从文件系统查找改为从模板库字典查找
- 统一内联模板和外部模板的查询接口
- 同名冲突时返回 WARNING 级别的验证问题
## Impact
### 受影响的代码模块
- `yaml2pptx.py`: 命令行参数修改
- `core/presentation.py`: 模板加载逻辑重构,移除 `template_cache`
- `core/template.py`: `from_data` 增加 `base_dir` 参数,`render` 中解析图片路径
- `loaders/yaml_loader.py`: 新增 `validate_template_library_yaml` 函数
- `validators/resource.py`: 修改模板验证逻辑,区分三种错误类型
- `validators/validator.py`: 参数 `template_dir` 改为 `template_file`
- `preview/server.py`: 参数 `template_dir` 改为 `template_file`
- `tests/`: 更新相关测试用例
### API 变更
**命令行参数**:
```bash
# 旧方式
yaml2pptx.py convert input.yaml --template-dir /path/to/templates/
# 新方式
yaml2pptx.py convert input.yaml --template /path/to/templates.yaml
```
**模板库文件格式**:
```yaml
# 新格式 (templates.yaml)
description: "公司标准模板库"
version: "1.0.0"
templates:
title-slide:
vars: ...
elements: ...
content-slide:
vars: ...
elements: ...
```
### 依赖变更
无新增依赖。
### 兼容性
- 不向后兼容:现有使用 `--template-dir` 的脚本需要更新为 `--template`
- 现有的单文件模板需要迁移到模板库格式