PPTX/openspec/changes/archive/2026-03-04-add-image-fit-modes/tasks.md

图片适配模式实现任务清单

1. 依赖配置

• 1.1 在 pyproject.toml 中添加 Pillow 依赖（不指定版本号）
• 1.2 运行 uv sync 安装新增依赖

2. 核心元素扩展

• 2.1 更新 core/elements.py 的 ImageElement 类，添加 fit 字段（可选，默认 None）
• 2.2 更新 core/elements.py 的 ImageElement 类，添加 background 字段（可选，默认 None）
• 2.3 更新 core/elements.py 的 ImageElement.post_init，验证 box 参数为必需
• 2.4 更新 core/elements.py 的 ImageElement.validate 方法，添加 fit 和 background 验证

3. 图片处理工具模块

• 3.1 创建 utils/image_utils.py 模块
• 3.2 实现 inches_to_pixels(inches, dpi) -> float 函数
• 3.3 实现 pixels_to_inches(pixels, dpi) -> float 函数
• 3.4 实现 apply_fit_mode(img, box_size, fit, background) -> PIL.Image 函数，支持四种模式
• 3.5 实现 create_canvas_with_background(size, background_color) -> PIL.Image 函数
• 3.6 在 apply_fit_mode 中使用 Pillow.ImageOps.contain 实现 contain 模式
• 3.7 在 apply_fit_mode 中使用 Pillow.ImageOps.cover 实现 cover 模式
• 3.8 在 apply_fit_mode 中实现 center 模式（不缩放，居中裁剪）
• 3.9 在 apply_fit_mode 中使用 LANCZOS 重采样算法保证图片质量

4. 验证器

• 4.1 创建 validators/image_config.py 模块
• 4.2 实现 validate_fit_value(fit) -> List[ValidationIssue] 函数，验证 fit 为有效值
• 4.3 实现 validate_background_color(color) -> List[ValidationIssue] 函数，验证颜色格式
• 4.4 实现 validate_dpi_value(dpi) -> List[ValidationIssue] 函数，验证 DPI 在合理范围
• 4.5 在主验证流程中集成图片配置验证器

5. PPTX 渲染器更新

• 5.1 更新 renderers/pptx_renderer.py，导入 Pillow 和 image_utils
• 5.2 重写 _render_image 方法，读取 metadata.dpi 配置
• 5.3 在 _render_image 中实现 stretch 模式（直接使用 python-pptx）
• 5.4 在 _render_image 中实现 contain 模式（使用 Pillow 处理）
• 5.5 在 _render_image 中实现 cover 模式（使用 Pillow 处理）
• 5.6 在 _render_image 中实现 center 模式（使用 Pillow 处理）
• 5.7 在 _render_image 中实现背景色填充（创建画布并粘贴图片）
• 5.8 在 _render_image 中添加图片处理失败的错误处理（抛出 ERROR）
• 5.9 更新 PptxGenerator 类，传递 dpi 参数到渲染方法

6. HTML 渲染器更新

• 6.1 更新 renderers/html_renderer.py 的 _render_image 方法
• 6.2 实现 fit 模式到 CSS object-fit 的映射（stretch->fill, contain->contain, cover->cover, center->none）
• 6.3 在 HTML 渲染中添加 object-position: center 样式（center 模式）
• 6.4 实现背景色支持（创建包装容器，应用 background-color）
• 6.5 更新 HTML 渲染器读取 metadata.dpi 配置
• 6.6 确保 HTML 和 PPTX 渲染效果一致

7. 加载器和配置支持

• 7.1 更新 loaders/yaml_loader.py，解析 metadata.dpi 配置
• 7.2 将 dpi 配置传递到 Presentation 对象
• 7.3 在 PptxGenerator 和 HtmlRenderer 中访问 dpi 配置

8. 单元测试

• 8.1 创建 tests/unit/test_image_utils.py
• 8.2 测试 inches_to_pixels 和 pixels_to_inches 函数
• 8.3 测试 apply_fit_mode 函数的四种模式
• 8.4 测试 create_canvas_with_background 函数
• 8.5 创建 tests/unit/test_validators/test_image_config.py
• 8.6 测试 validate_fit_value 函数（有效值和无效值）
• 8.7 测试 validate_background_color 函数（有效颜色和无效颜色）
• 8.8 测试 validate_dpi_value 函数（合理范围和超出范围）
• 8.9 更新 tests/unit/test_elements.py，测试 ImageElement 新字段

9. 集成测试

• 9.1 创建 tests/integration/test_image_fit_modes.py
• 9.2 测试 stretch 模式的 PPTX 渲染
• 9.3 测试 contain 模式的 PPTX 渲染（图片比 box 大）
• 9.4 测试 contain 模式的 PPTX 渲染（图片比 box 小）
• 9.5 测试 contain 模式的 PPTX 渲染（带背景色）
• 9.6 测试 cover 模式的 PPTX 渲染（图片比 box 大）
• 9.7 测试 cover 模式的 PPTX 渲染（图片比 box 小）
• 9.8 测试 center 模式的 PPTX 渲染（带背景色）
• 9.9 测试不同 DPI 配置的渲染结果
• 9.10 测试图片处理失败时的错误处理
• 9.11 测试 HTML 渲染器的四种 fit 模式
• 9.12 测试 HTML 渲染器的背景色支持
• 9.13 对比 HTML 和 PPTX 渲染效果的一致性

10. 端到端测试

• 10.1 创建测试 YAML 文件，包含所有 fit 模式
• 10.2 创建测试 YAML 文件，包含背景色配置
• 10.3 创建测试 YAML 文件，包含 DPI 配置
• 10.4 创建测试 YAML 文件，包含无效参数（测试验证）
• 10.5 运行 check 命令，验证错误检测
• 10.6 运行 convert 命令，验证 PPTX 生成
• 10.7 运行 preview 命令，验证 HTML 预览

11. 文档更新

• 11.1 更新 README.md，添加图片适配模式章节
• 11.2 在 README.md 中添加 fit 参数说明和示例
• 11.3 在 README.md 中添加 background 参数说明和示例
• 11.4 在 README.md 中添加 metadata.dpi 配置说明
• 11.5 更新 README_DEV.md，添加图片处理架构说明
• 11.6 在 README_DEV.md 中说明 Pillow 依赖和用途
• 11.7 在 README_DEV.md 中说明 image_utils 模块的设计

12. 向后兼容性验证

• 12.1 测试现有 YAML 文件（无 fit 参数）仍能正常转换
• 12.2 测试现有 YAML 文件的渲染结果与之前一致
• 12.3 验证未指定 fit 时默认使用 stretch 模式