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:
102
README.md
102
README.md
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user