# Loaders 模块

`loaders/yaml_loader.py` 负责 YAML 文件加载和验证。

## 职责

- YAML 文件加载
- 演示文稿结构验证
- 内联模板验证
- 外部模板验证

## 包含的内容

### YAMLError

自定义异常类：

```python
class YAMLError(Exception):
    """YAML 相关错误"""
    pass
```

### load_yaml_file()

加载 YAML 文件：

```python
def load_yaml_file(file_path):
    """加载 YAML 文件并返回解析后的数据"""
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            data = yaml.safe_load(f)
        return data
    except yaml.YAMLError as e:
        raise YAMLError(f"YAML 语法错误: {e}")
    except FileNotFoundError:
        raise YAMLError(f"文件不存在: {file_path}")
```

### validate_presentation_yaml()

验证演示文稿结构：

```python
def validate_presentation_yaml(data, file_path):
    """验证演示文稿 YAML 结构"""
    # 检查必需字段
    if 'metadata' not in data:
        raise YAMLError(f"缺少 metadata 字段: {file_path}")

    if 'slides' not in data:
        raise YAMLError(f"缺少 slides 字段: {file_path}")

    # 验证 metadata
    metadata = data['metadata']
    if 'size' not in metadata:
        raise YAMLError(f"metadata 缺少 size 字段: {file_path}")

    if metadata['size'] not in ['16:9', '4:3']:
        raise YAMLError(f"无效的 size 值: {metadata['size']}")

    # 验证内联模板（如果有）
    if 'templates' in data:
        validate_templates_yaml(data['templates'])

    # 验证幻灯片
    for slide in data['slides']:
        # 验证 enabled 字段
        if 'enabled' in slide:
            if not isinstance(slide['enabled'], bool):
                raise YAMLError(f"enabled 必须是布尔值: {file_path}")
```

### validate_template_yaml()

验证外部模板结构：

```python
def validate_template_yaml(template_data, template_name):
    """验证外部模板结构"""
    if 'elements' not in template_data:
        raise YAMLError(f"模板缺少 elements 字段: {template_name}")

    if 'vars' in template_data:
        for var in template_data['vars']:
            if 'name' not in var:
                raise YAMLError(f"变量缺少 name 字段: {template_name}")
```

### validate_templates_yaml()

验证内联模板结构：

```python
def validate_templates_yaml(templates):
    """验证内联模板结构"""
    if not isinstance(templates, dict):
        raise YAMLError("templates 必须是字典类型")

    for name, template_data in templates.items():
        validate_template_yaml(template_data, f"templates.{name}")

        # 检测默认值中引用不存在的变量
        vars_def = {v['name']: v for v in template_data.get('vars', [])}
        for var in template_data.get('vars', []):
            if 'default' in var:
                # 检查默认值是否引用了不存在的变量
                # 实现省略...
```

## 内联模板验证

内联模板验证包括：
- 结构验证（是否为字典）
- 元素验证（是否有 elements 字段）
- 变量定义验证（是否有 name 字段）
- 默认值验证（检测循环引用）

## enabled 字段验证

验证 `enabled` 字段必须是布尔值：

```python
if 'enabled' in slide:
    if not isinstance(slide['enabled'], bool):
        raise YAMLError(f"enabled 必须是布尔值，不能是字符串或条件表达式")
```

## 相关文档

- [架构设计](../architecture.md) - 代码结构
- [验证器模块](validators.md) - 验证详解

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