PPTX/docs/reference/validation.md

# 验证功能

yaml2pptx 提供强大的验证功能，在转换前自动检查 YAML 文件，提前发现问题。

## 验证级别

验证结果分为三个级别：

### ERROR（错误）

阻止转换的严重问题：
- 文件不存在（图片、模板文件等）
- YAML 语法错误
- 必需的变量未提供
- 无效的数据类型

### WARNING（警告）

影响视觉效果但不阻止转换的问题：
- 元素超出页面范围
- 字体大小过小或过大
- 颜色格式不规范但可解析

### INFO（信息）

优化建议和提示：
- 性能优化建议
- 最佳实践提示

## 验证内容

### YAML 语法和结构

- 检查 YAML 语法是否正确
- 检查必需字段是否存在
- 检查数据类型是否正确

### 元素边界

- 检查元素是否超出页面范围
- 0.1 英寸容忍度内的超出会发出警告

### 资源文件

- 检查图片文件是否存在
- 检查模板文件是否存在
- 验证文件路径是否有效

### 颜色格式

- 检查颜色格式是否正确（#RGB 或 #RRGGBB）
- 检查颜色值是否有效

### 字体配置

- 检查字体大小是否合理（<6 或 >72 会警告）
- 检查字体引用是否存在
- 检查字体引用循环

### 表格数据

- 检查表格数据一致性
- 检查列数是否匹配

## 使用验证

### 独立验证

```bash
uv run yaml2pptx.py check presentation.yaml
```

### 使用模板时验证

```bash
uv run yaml2pptx.py check presentation.yaml --template ./templates.yaml
```

### 自动验证

转换时默认会自动验证：

```bash
uv run yaml2pptx.py convert presentation.yaml output.pptx
```

### 跳过验证

```bash
uv run yaml2pptx.py convert presentation.yaml output.pptx --skip-validation
```

## 验证结果示例

### 有错误和警告

```
正在检查 YAML 文件...

- 错误 (2):
  [幻灯片 2, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
  [幻灯片 3, 元素 2] 图片文件不存在: logo.png

-  警告 (1):
  [幻灯片 1, 元素 1] 元素右边界超出: 10.50 > 10

检查完成: 发现 2 个错误, 1 个警告
转换已终止
```

### 验证通过

```
正在检查 YAML 文件...

检查完成: 未发现问题
```

### 仅警告

```
正在检查 YAML 文件...

-  警告 (2):
  [幻灯片 1, 元素 1] 元素右边界超出: 10.05 > 10
  [幻灯片 2, 元素 2] 字体大小过小: 5

检查完成: 发现 2 个警告
```

## 常见验证错误

### 文件不存在

```
错误: 图片文件未找到: images/logo.png
```

**解决方法**：检查图片路径是否正确

### YAML 语法错误

```
错误: YAML 语法错误: 第 15 行
```

**解决方法**：检查缩进和语法，确保 YAML 格式正确

### 缺少必需变量

```
错误: 缺少必需变量: title
```

**解决方法**：在 `vars` 中提供该变量

### 无效颜色格式

```
错误: 无效的颜色格式: red (应为 #RRGGBB)
```

**解决方法**：使用 `#ff0000` 格式

## 验证容忍度

几何验证时，允许 0.1 英寸的容忍度：

- 超出 ≤ 0.1 英寸：不报错
- 超出 > 0.1 英寸：发出警告

```python
TOLERANCE = 0.1  # 英寸

if right > slide_width + TOLERANCE:
    # 报告 WARNING
```

## 最佳实践

1. **开发时频繁验证**：使用 `check` 命令快速验证
2. **修复所有错误**：确保没有 ERROR 级别的问题
3. **关注警告**：WARNING 虽不阻止转换，但可能影响视觉效果
4. **使用预览模式**：结合预览模式查看实际效果

## 相关文档

- [命令行选项](commands.md) - 所有命令和参数
- [故障排查](../troubleshooting.md) - 常见问题解决

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