lanyuanxiaoyao
19d6661381
- 支持四种图片适配模式：stretch、contain、cover、center - 支持背景色填充功能（contain 和 center 模式） - 支持文档级 DPI 配置（metadata.dpi） - PPTX 渲染器集成 Pillow 实现高质量图片处理 - HTML 渲染器使用 CSS object-fit 实现相同效果 - 添加完整的单元测试、集成测试和端到端测试 - 更新 README 文档和架构文档 - 模块化设计：utils/image_utils.py 图片处理工具模块 - 添加图片配置验证器：validators/image_config.py - 向后兼容：未指定 fit 时默认使用 stretch 模式
115 lines
5.7 KiB
Markdown
115 lines
5.7 KiB
Markdown
# 图片适配模式实现任务清单
|
||
|
||
## 1. 依赖配置
|
||
|
||
- [x] 1.1 在 pyproject.toml 中添加 Pillow 依赖（不指定版本号）
|
||
- [x] 1.2 运行 `uv sync` 安装新增依赖
|
||
|
||
## 2. 核心元素扩展
|
||
|
||
- [x] 2.1 更新 `core/elements.py` 的 ImageElement 类，添加 `fit` 字段（可选，默认 None）
|
||
- [x] 2.2 更新 `core/elements.py` 的 ImageElement 类，添加 `background` 字段（可选，默认 None）
|
||
- [x] 2.3 更新 `core/elements.py` 的 ImageElement.__post_init__，验证 box 参数为必需
|
||
- [x] 2.4 更新 `core/elements.py` 的 ImageElement.validate 方法，添加 fit 和 background 验证
|
||
|
||
## 3. 图片处理工具模块
|
||
|
||
- [x] 3.1 创建 `utils/image_utils.py` 模块
|
||
- [x] 3.2 实现 `inches_to_pixels(inches, dpi) -> float` 函数
|
||
- [x] 3.3 实现 `pixels_to_inches(pixels, dpi) -> float` 函数
|
||
- [x] 3.4 实现 `apply_fit_mode(img, box_size, fit, background) -> PIL.Image` 函数，支持四种模式
|
||
- [x] 3.5 实现 `create_canvas_with_background(size, background_color) -> PIL.Image` 函数
|
||
- [x] 3.6 在 `apply_fit_mode` 中使用 Pillow.ImageOps.contain 实现 contain 模式
|
||
- [x] 3.7 在 `apply_fit_mode` 中使用 Pillow.ImageOps.cover 实现 cover 模式
|
||
- [x] 3.8 在 `apply_fit_mode` 中实现 center 模式（不缩放，居中裁剪）
|
||
- [x] 3.9 在 `apply_fit_mode` 中使用 LANCZOS 重采样算法保证图片质量
|
||
|
||
## 4. 验证器
|
||
|
||
- [x] 4.1 创建 `validators/image_config.py` 模块
|
||
- [x] 4.2 实现 `validate_fit_value(fit) -> List[ValidationIssue]` 函数，验证 fit 为有效值
|
||
- [x] 4.3 实现 `validate_background_color(color) -> List[ValidationIssue]` 函数，验证颜色格式
|
||
- [x] 4.4 实现 `validate_dpi_value(dpi) -> List[ValidationIssue]` 函数，验证 DPI 在合理范围
|
||
- [x] 4.5 在主验证流程中集成图片配置验证器
|
||
|
||
## 5. PPTX 渲染器更新
|
||
|
||
- [x] 5.1 更新 `renderers/pptx_renderer.py`，导入 Pillow 和 image_utils
|
||
- [x] 5.2 重写 `_render_image` 方法，读取 metadata.dpi 配置
|
||
- [x] 5.3 在 `_render_image` 中实现 stretch 模式（直接使用 python-pptx）
|
||
- [x] 5.4 在 `_render_image` 中实现 contain 模式（使用 Pillow 处理）
|
||
- [x] 5.5 在 `_render_image` 中实现 cover 模式（使用 Pillow 处理）
|
||
- [x] 5.6 在 `_render_image` 中实现 center 模式（使用 Pillow 处理）
|
||
- [x] 5.7 在 `_render_image` 中实现背景色填充（创建画布并粘贴图片）
|
||
- [x] 5.8 在 `_render_image` 中添加图片处理失败的错误处理（抛出 ERROR）
|
||
- [x] 5.9 更新 PptxGenerator 类，传递 dpi 参数到渲染方法
|
||
|
||
## 6. HTML 渲染器更新
|
||
|
||
- [x] 6.1 更新 `renderers/html_renderer.py` 的 `_render_image` 方法
|
||
- [x] 6.2 实现 fit 模式到 CSS object-fit 的映射（stretch->fill, contain->contain, cover->cover, center->none）
|
||
- [x] 6.3 在 HTML 渲染中添加 object-position: center 样式（center 模式）
|
||
- [x] 6.4 实现背景色支持（创建包装容器，应用 background-color）
|
||
- [x] 6.5 更新 HTML 渲染器读取 metadata.dpi 配置
|
||
- [x] 6.6 确保 HTML 和 PPTX 渲染效果一致
|
||
|
||
## 7. 加载器和配置支持
|
||
|
||
- [x] 7.1 更新 `loaders/yaml_loader.py`，解析 metadata.dpi 配置
|
||
- [x] 7.2 将 dpi 配置传递到 Presentation 对象
|
||
- [x] 7.3 在 PptxGenerator 和 HtmlRenderer 中访问 dpi 配置
|
||
|
||
## 8. 单元测试
|
||
|
||
- [x] 8.1 创建 `tests/unit/test_image_utils.py`
|
||
- [x] 8.2 测试 `inches_to_pixels` 和 `pixels_to_inches` 函数
|
||
- [x] 8.3 测试 `apply_fit_mode` 函数的四种模式
|
||
- [x] 8.4 测试 `create_canvas_with_background` 函数
|
||
- [x] 8.5 创建 `tests/unit/test_validators/test_image_config.py`
|
||
- [x] 8.6 测试 `validate_fit_value` 函数（有效值和无效值）
|
||
- [x] 8.7 测试 `validate_background_color` 函数（有效颜色和无效颜色）
|
||
- [x] 8.8 测试 `validate_dpi_value` 函数（合理范围和超出范围）
|
||
- [x] 8.9 更新 `tests/unit/test_elements.py`，测试 ImageElement 新字段
|
||
|
||
## 9. 集成测试
|
||
|
||
- [x] 9.1 创建 `tests/integration/test_image_fit_modes.py`
|
||
- [x] 9.2 测试 stretch 模式的 PPTX 渲染
|
||
- [x] 9.3 测试 contain 模式的 PPTX 渲染（图片比 box 大）
|
||
- [x] 9.4 测试 contain 模式的 PPTX 渲染（图片比 box 小）
|
||
- [x] 9.5 测试 contain 模式的 PPTX 渲染（带背景色）
|
||
- [x] 9.6 测试 cover 模式的 PPTX 渲染（图片比 box 大）
|
||
- [x] 9.7 测试 cover 模式的 PPTX 渲染（图片比 box 小）
|
||
- [x] 9.8 测试 center 模式的 PPTX 渲染（带背景色）
|
||
- [x] 9.9 测试不同 DPI 配置的渲染结果
|
||
- [x] 9.10 测试图片处理失败时的错误处理
|
||
- [x] 9.11 测试 HTML 渲染器的四种 fit 模式
|
||
- [x] 9.12 测试 HTML 渲染器的背景色支持
|
||
- [x] 9.13 对比 HTML 和 PPTX 渲染效果的一致性
|
||
|
||
## 10. 端到端测试
|
||
|
||
- [x] 10.1 创建测试 YAML 文件，包含所有 fit 模式
|
||
- [x] 10.2 创建测试 YAML 文件，包含背景色配置
|
||
- [x] 10.3 创建测试 YAML 文件，包含 DPI 配置
|
||
- [x] 10.4 创建测试 YAML 文件，包含无效参数（测试验证）
|
||
- [x] 10.5 运行 `check` 命令，验证错误检测
|
||
- [x] 10.6 运行 `convert` 命令，验证 PPTX 生成
|
||
- [x] 10.7 运行 `preview` 命令，验证 HTML 预览
|
||
|
||
## 11. 文档更新
|
||
|
||
- [x] 11.1 更新 `README.md`，添加图片适配模式章节
|
||
- [x] 11.2 在 README.md 中添加 fit 参数说明和示例
|
||
- [x] 11.3 在 README.md 中添加 background 参数说明和示例
|
||
- [x] 11.4 在 README.md 中添加 metadata.dpi 配置说明
|
||
- [x] 11.5 更新 `README_DEV.md`，添加图片处理架构说明
|
||
- [x] 11.6 在 README_DEV.md 中说明 Pillow 依赖和用途
|
||
- [x] 11.7 在 README_DEV.md 中说明 image_utils 模块的设计
|
||
|
||
## 12. 向后兼容性验证
|
||
|
||
- [x] 12.1 测试现有 YAML 文件（无 fit 参数）仍能正常转换
|
||
- [x] 12.2 测试现有 YAML 文件的渲染结果与之前一致
|
||
- [x] 12.3 验证未指定 fit 时默认使用 stretch 模式
|