# 内联模板

内联模板允许你在 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: "使用内联模板"
```

## 变量定义

### required 变量

```yaml
vars:
  - name: title
    required: true
```

### 可选变量与默认值

```yaml
vars:
  - name: subtitle
    required: false
    default: ""
```

## 内联模板特性

- 支持变量替换和条件渲染
- 可以与外部模板混合使用
- 无需指定 `--template` 参数
- 内联模板不能相互引用
- 内联和外部模板同名时会发出警告，优先使用内联模板

## 何时使用内联模板

**适合使用内联模板**：
- 模板仅在单个文档中使用
- 快速原型开发
- 简单的模板定义（1-3 个元素）
- 文档自包含，无需外部依赖

**适合使用外部模板**：
- 需要跨多个文档复用
- 复杂的模板定义（>5 个元素）
- 团队共享的模板库
- 需要版本控制和独立维护

## 最佳实践

### 1. 命名规范

- 内联模板使用描述性名称（如 `title-slide`, `content-slide`）
- 避免与外部模板同名，否则会发出警告
- 使用一致的命名风格（kebab-case 推荐）

### 2. 模板大小

- 内联模板建议不超过 50 行
- 超过 50 行考虑拆分或使用外部模板
- 保持 YAML 文件可读性

### 3. 混合使用

- 可以在同一文档中混合使用内联和外部模板
- 通用模板使用外部模板（如标题页、结束页）
- 文档特定模板使用内联模板

### 4. 迁移策略

- 原型阶段使用内联模板快速迭代
- 模板稳定后，如需复用则迁移到外部模板
- 使用 `--template` 参数指定外部模板库文件

## 内联模板限制

- 内联模板不能相互引用（会报错）
- 内联和外部模板同名时会发出警告，优先使用内联模板
- 内联模板不支持继承或组合

## 示例

### 简单标题页

```yaml
metadata:
  size: "16:9"

templates:
  simple-title:
    vars:
      - name: title
        required: true
    elements:
      - type: text
        box: [1, 2.5, 8, 1]
        content: "{title}"
        font:
          size: 44
          bold: true
          align: center

slides:
  - template: simple-title
    vars:
      title: "欢迎使用 yaml2pptx"
```

### 带条件渲染的模板

```yaml
templates:
  optional-subtitle:
    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.2, 8, 0.6]
        content: "{subtitle}"
        visible: "{subtitle != ''}"
        font:
          size: 24
          align: center

slides:
  - template: optional-subtitle
    vars:
      title: "标题"
      subtitle: "有副标题"

  - template: optional-subtitle
    vars:
      title: "只有标题"
      # subtitle 省略，使用默认值 ""
```

## 相关文档

- [外部模板库](external-library.md) - 独立的模板库文件
- [混合模式](mixing-mode.md) - 模板与自定义元素组合
- [条件渲染](condition-rendering.md) - 元素和页面的条件显示

[返回文档索引](../README.md)