1
0

feat: 添加内联模板支持

支持在 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 字段时行为不变。
This commit is contained in:
2026-03-03 15:59:55 +08:00
parent 2ba1bd7272
commit 01eacb0b97
15 changed files with 1277 additions and 25 deletions

102
README.md
View File

@@ -192,9 +192,105 @@ slides:
## 📋 模板系统
模板允许你定义可复用的幻灯片布局。
模板允许你定义可复用的幻灯片布局。yaml2pptx 支持两种模板方式:
### 创建模板
- **外部模板**:独立的 YAML 文件,适合跨文档复用
- **内联模板**:在源文件中定义,适合单文档使用
### 内联模板
内联模板允许你在 YAML 源文件中直接定义模板,无需创建单独的模板文件。
#### 定义内联模板
在 YAML 文件顶层添加 `templates` 字段:
```yaml
metadata:
size: "16:9"
templates:
title-slide:
vars:
- name: title
required: true
- name: subtitle
required: false
default: ""
elements:
- type: text
box: [1, 2, 8, 1]
content: "{title}"
font:
size: 44
bold: true
align: center
- type: text
box: [1, 3.5, 8, 0.5]
content: "{subtitle}"
visible: "{subtitle != ''}"
font:
size: 24
align: center
slides:
- template: title-slide
vars:
title: "我的演示文稿"
subtitle: "使用内联模板"
```
#### 内联模板特性
- ✅ 支持变量替换和条件渲染
- ✅ 可以与外部模板混合使用
- ✅ 无需指定 `--template-dir` 参数
- ⚠️ 内联模板不能相互引用
- ⚠️ 内联和外部模板不能同名(会报错)
#### 何时使用内联模板
**适合使用内联模板**
- 模板仅在单个文档中使用
- 快速原型开发
- 简单的模板定义1-3 个元素)
- 文档自包含,无需外部依赖
**适合使用外部模板**
- 需要跨多个文档复用
- 复杂的模板定义(>5 个元素)
- 团队共享的模板库
- 需要版本控制和独立维护
**最佳实践**
1. **命名规范**
- 内联模板使用描述性名称(如 `title-slide`, `content-slide`
- 避免与外部模板同名,否则会报错
- 使用一致的命名风格kebab-case 推荐)
2. **模板大小**
- 内联模板建议不超过 50 行
- 超过 50 行考虑拆分或使用外部模板
- 保持 YAML 文件可读性
3. **混合使用**
- 可以在同一文档中混合使用内联和外部模板
- 通用模板使用外部模板(如标题页、结束页)
- 文档特定模板使用内联模板
4. **迁移策略**
- 原型阶段使用内联模板快速迭代
- 模板稳定后,如需复用则迁移到外部模板
- 使用 `--template-dir` 参数指定外部模板目录
#### 内联模板限制
- ⚠️ 内联模板不能相互引用(会报错)
- ⚠️ 内联和外部模板不能同名(会报错)
- ⚠️ 内联模板不支持继承或组合
### 创建外部模板
创建模板文件 `templates/title-slide.yaml`
@@ -234,7 +330,7 @@ elements:
align: center
```
### 使用模板
### 使用外部模板
```yaml
slides: