lanyuanxiaoyao
f1aae96a04
主要变更： - 将 templates_dir 参数改为 template_file，支持单个模板库 YAML 文件 - 添加模板库 YAML 验证功能 - 为模板添加 base_dir 支持，正确解析相对路径资源 - 内联模板与外部模板同名时改为警告（内联优先） - 移除模板缓存机制，直接使用模板库字典 - 更新所有相关测试以适配新的模板加载方式 此重构简化了模板管理，使模板资源的路径解析更加清晰明确。
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
## 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`
|
||
- 现有的单文件模板需要迁移到模板库格式
|