# 条件渲染

条件渲染允许你根据变量值控制元素和幻灯片的显示。

## 元素级条件渲染

使用 `visible` 属性控制元素显示，支持强大的条件表达式：

### 基本示例

```yaml
# 简单比较
- type: text
  content: "有数据"
  visible: "{count > 0}"

# 字符串比较
- type: text
  content: "草稿状态"
  visible: "{status == 'draft'}"

# 非空检查（向后兼容）
- type: text
  content: "{subtitle}"
  visible: "{subtitle != ''}"
```

### 支持的表达式类型

#### 1. 比较运算

`==`, `!=`, `>`, `<`, `>=`, `<=`

```yaml
visible: "{score >= 60}"
visible: "{price <= 100}"
```

#### 2. 逻辑运算

`and`, `or`, `not`

```yaml
visible: "{count > 0 and status == 'active'}"
visible: "{is_draft or is_preview}"
visible: "{not (count == 0)}"
```

#### 3. 成员测试

`in`, `not in`

```yaml
visible: "{status in ['draft', 'review', 'published']}"
visible: "{level in (1, 2, 3)}"
visible: "{'test' in version}"  # 字符串包含
```

#### 4. 数学运算

`+`, `-`, `*`, `/`, `%`, `**`

```yaml
visible: "{(price * discount) > 50}"
visible: "{(total / count) >= 10}"
```

#### 5. 内置函数

`int()`, `float()`, `str()`, `len()`, `bool()`, `abs()`, `min()`, `max()`

```yaml
visible: "{len(items) > 0}"
visible: "{int(value) > 100}"
```

### 复杂条件示例

```yaml
# 范围检查
- type: text
  content: "评分: {score}"
  visible: "{score >= 60 and score <= 100}"

# 多条件组合
- type: text
  content: "管理员或高分用户"
  visible: "{is_admin or (score >= 90)}"

# 嵌套条件
- type: text
  content: "符合条件"
  visible: "{((count > 0) and (status == 'active')) or (is_admin and (level >= 3))}"
```

## 页面级启用控制

使用 `enabled` 参数控制整个幻灯片是否渲染：

```yaml
slides:
  # 正常渲染的幻灯片
  - template: title-slide
    vars:
      title: "主标题"

  # 临时禁用的幻灯片（开发调试）
  - enabled: false
    template: work-in-progress
    vars:
      title: "未完成的内容"

  # 继续渲染后续幻灯片
  - template: content-slide
    vars:
      title: "内容页"
```

### enabled 参数说明

- **类型**：布尔值（`true` 或 `false`）
- **默认值**：`true`（未指定时默认启用）
- **用途**：临时禁用幻灯片，无需删除或注释 YAML 内容
- **场景**：开发调试、版本控制、A/B 测试

### enabled vs visible 的区别

| 特性 | `enabled`（页面级） | `visible`（元素级） |
|------|-------------------|-------------------|
| 作用范围 | 整个幻灯片 | 单个元素 |
| 类型 | 布尔值 | 条件表达式 |
| 判断时机 | 加载时（静态） | 渲染时（动态） |
| 使用场景 | 临时禁用页面 | 条件显示元素 |

### 示例

```yaml
slides:
  # 页面启用，但副标题元素可能隐藏
  - enabled: true
    template: title-slide
    vars:
      title: "标题"
      subtitle: ""  # 空字符串，元素级 visible 会隐藏副标题

  # 整页禁用，不渲染
  - enabled: false
    elements:
      - type: text
        content: "这一页不会出现在最终 PPTX 中"
        box: [1, 1, 8, 1]
        font: {size: 44}
```

## 安全策略

条件表达式评估使用 simpleeval 库，具有以下安全限制：

- 表达式最大长度限制：500 字符
- 禁止属性访问（obj.attr）
- 禁止函数定义（lambda, def）
- 禁止模块导入（import）
- 白名单函数限制

## 错误处理

常见错误信息：

- `条件表达式中的变量未定义` - 使用了未在 vars 中定义的变量
- `条件表达式中使用了不支持的函数` - 使用了白名单之外的函数
- `条件表达式使用了不支持的语法特性` - 使用了禁止的语法
- `不支持属性访问` - 尝试访问对象属性
- `条件表达式语法错误` - 表达式语法有误

## 相关文档

- [内联模板](inline.md) - 在源文件中定义模板
- [混合模式](mixing-mode.md) - 模板与自定义元素组合

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