# 混合模式

混合模式允许你在使用模板的同时添加自定义元素，实现更灵活的布局组合。

## 基本用法

在使用模板的幻灯片中，同时指定 `template` 和 `elements` 字段：

```yaml
slides:
  # 混合模式：模板 + 自定义元素
  - template: standard-header
    vars:
      title: "混合模式示例"
      theme_color: "#3949ab"
    elements:
      # 自定义内容区域
      - type: text
        box: [1, 1.5, 8, 1]
        content: "这是自定义内容"
        font:
          size: 24
      # 自定义形状
      - type: shape
        shape: rectangle
        box: [1, 3, 8, 2]
        fill: "#f5f5f5"
```

## 变量共享

自定义元素可以访问模板中定义的变量：

```yaml
templates:
  branded-header:
    vars:
      - name: title
      - name: theme_color
        default: "#3949ab"
    elements:
      - type: shape
        box: [0, 0, 10, 0.8]
        fill: "{theme_color}"
      - type: text
        box: [0.5, 0.2, 9, 0.5]
        content: "{title}"

slides:
  - template: branded-header
    vars:
      title: "我的页面"
      theme_color: "#4caf50"
    elements:
      # 自定义元素使用模板变量
      - type: shape
        box: [1, 2, 8, 3]
        fill: "{theme_color}"  # 使用模板的 theme_color
```

## 元素渲染顺序

混合模式中，元素按以下顺序渲染（z 轴顺序）：

1. **模板元素**（先渲染，在底层）
2. **自定义元素**（后渲染，在上层）

这意味着自定义元素会覆盖在模板元素之上。

```yaml
slides:
  - template: background-template  # 提供背景和头部
    vars:
      title: "标题"
    elements:
      # 这些元素会显示在模板元素之上
      - type: shape
        box: [2, 2, 6, 3]
        fill: "#ffffff"  # 白色框会覆盖背景
```

## 使用场景

**适合使用混合模式**：

- 复用统一的头部/底部，自定义中间内容
- 使用模板提供的背景和品牌元素，添加页面特定内容
- 需要在标准布局基础上添加特殊元素

## 示例

### 统一头部 + 自定义内容

```yaml
templates:
  standard-header:
    vars:
      - name: title
    elements:
      # 统一的头部样式
      - type: shape
        box: [0, 0, 10, 0.8]
        fill: "#3949ab"
      - type: text
        box: [0.5, 0.2, 9, 0.5]
        content: "{title}"
        font:
          color: "#ffffff"

slides:
  # 页面 1：头部 + 文本内容
  - template: standard-header
    vars:
      title: "文本页面"
    elements:
      - type: text
        box: [1, 1.5, 8, 3]
        content: "页面内容..."

  # 页面 2：头部 + 表格
  - template: standard-header
    vars:
      title: "数据页面"
    elements:
      - type: table
        position: [1, 1.5]
        col_widths: [3, 3]
        data:
          - ["列1", "列2"]
          - ["数据1", "数据2"]

  # 页面 3：头部 + 图片
  - template: standard-header
    vars:
      title: "图片页面"
    elements:
      - type: image
        box: [2, 1.5, 6, 3.5]
        src: "chart.png"
```

### 背景模板 + 覆盖层

```yaml
templates:
  gradient-bg:
    vars:
      - name: accent_color
        default: "#3498db"
    elements:
      - type: shape
        box: [0, 0, 10, 5.625]
        fill: "{accent_color}"

slides:
  - template: gradient-bg
    vars:
      accent_color: "#9b59b6"
    elements:
      # 白色内容框覆盖在渐变背景上
      - type: shape
        box: [1, 1, 8, 3.625]
        fill: "#ffffff"
      - type: text
        box: [1.5, 2, 7, 2]
        content: "内容区域"
        font:
          size: 32
```

## 向后兼容性

混合模式完全向后兼容：

- **纯模板模式**：只指定 `template`，行为不变
- **纯自定义模式**：只指定 `elements`，行为不变
- **混合模式**：同时指定 `template` 和 `elements`，新功能

```yaml
slides:
  # 纯模板模式（原有行为）
  - template: title-slide
    vars:
      title: "标题"

  # 纯自定义模式（原有行为）
  - elements:
      - type: text
        content: "自定义内容"

  # 混合模式（新功能）
  - template: title-slide
    vars:
      title: "标题"
    elements:
      - type: text
        content: "额外内容"
```

## 幻灯片 description 字段

幻灯片可以包含可选的 `description` 字段，用于描述该幻灯片的作用和内容。**`description` 内容会自动写入 PPT 备注页**，方便在演示时查看演讲说明：

```yaml
slides:
  - description: "介绍项目背景和目标"
    template: title-slide
    vars:
      title: "项目背景"

  - description: "展示核心功能特性"
    elements:
      - type: text
        content: "功能特性"
```

**注意事项**：
- 仅幻灯片级别的 `description` 会写入备注
- 模板的 `description` 不会继承到幻灯片备注
- `metadata.description` 用于描述整个演示文稿，不写入单个幻灯片备注

## 相关文档

- [内联模板](inline.md) - 在源文件中定义模板
- [外部模板库](external-library.md) - 独立的模板库文件
- [条件渲染](condition-rendering.md) - 元素和页面的条件显示

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