Files

lanyuanxiaoyao 124ef0e5ce refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷：
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行，仅保留概览和导航
- 删除 README_DEV.md，内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure

2026-03-06 15:11:36 +08:00

3.5 KiB

Raw Blame History

验证功能

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

验证级别

验证结果分为三个级别：

ERROR（错误）

阻止转换的严重问题：

文件不存在（图片、模板文件等）
YAML 语法错误
必需的变量未提供
无效的数据类型

WARNING（警告）

影响视觉效果但不阻止转换的问题：

元素超出页面范围
字体大小过小或过大
颜色格式不规范但可解析

INFO（信息）

优化建议和提示：

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

验证内容

YAML 语法和结构

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

元素边界

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

资源文件

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

颜色格式

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

字体配置

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

表格数据

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

使用验证

独立验证

uv run yaml2pptx.py check presentation.yaml

使用模板时验证

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

自动验证

转换时默认会自动验证：

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

跳过验证

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 英寸：发出警告

TOLERANCE = 0.1  # 英寸

if right > slide_width + TOLERANCE:
    # 报告 WARNING

最佳实践

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

3.5 KiB Raw Blame History Unescape Escape