1
0

feat: 添加图片适配模式支持

- 支持四种图片适配模式: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 模式
This commit is contained in:
2026-03-04 10:29:21 +08:00
parent 16ca9d77cd
commit 19d6661381
32 changed files with 2310 additions and 57 deletions

View File

@@ -67,6 +67,49 @@ yaml2pptx.py (入口)
- 核心层不依赖其他业务模块
- 验证层可以调用核心层的元素验证方法
### 图片处理架构
图片适配模式功能采用分层设计,将图片处理逻辑与渲染逻辑分离:
```
ImageElement (核心层)
↓ 定义 fit/background 字段
utils/image_utils.py (工具层)
↓ 提供图片处理函数
├─→ apply_fit_mode() - 应用适配模式
├─→ create_canvas_with_background() - 创建背景画布
└─→ inches_to_pixels() / pixels_to_inches() - 单位转换
↓ 使用 Pillow (PIL)
renderers/pptx_renderer.py (渲染层)
↓ 调用 image_utils 处理图片
└─→ 将处理后的图片添加到 PPTX
renderers/html_renderer.py (渲染层)
└─→ 使用 CSS object-fit 实现相同效果
```
**设计要点**
1. **Pillow 依赖**
- 用于高质量图片处理(缩放、裁剪、画布创建)
- 使用 LANCZOS 重采样算法确保最佳质量
- 支持 RGB 模式和透明度处理
2. **适配模式实现**
- **stretch**:直接使用 `Image.resize()`
- **contain**:使用 `ImageOps.contain()` 保持宽高比
- **cover**:使用 `ImageOps.cover()` + 中心裁剪
- **center**:不缩放,使用 `Image.crop()` 裁剪超出部分
3. **DPI 配置**
-`metadata.dpi` 配置,默认 96
- 通过 Presentation → Renderer 传递
- 用于像素与英寸的转换计算
4. **向后兼容性**
- `fit``background` 参数可选
- 未指定 `fit` 时默认使用 `stretch` 模式
- 现有 YAML 文件无需修改即可正常工作
## 模块职责
### 1. yaml2pptx.py入口层
@@ -84,11 +127,23 @@ yaml2pptx.py (入口)
- 维护独立的 `slide_index` 计数器,只统计实际渲染的幻灯片
- 进度日志显示准确的渲染数量(不包括禁用的幻灯片)
### 2. utils.py(工具层)
- **职责**:通用工具函数
### 2. utils/(工具层)
- **职责**:通用工具函数和图片处理
- **包含**
- 日志函数:`log_info()`, `log_success()`, `log_error()`, `log_progress()`
- 颜色转换:`hex_to_rgb()`, `validate_color()`
- `utils/__init__.py` - 日志和颜色工具
- 日志函数:`log_info()`, `log_success()`, `log_error()`, `log_progress()`
- 颜色转换:`hex_to_rgb()`, `validate_color()`
- `utils/image_utils.py` - 图片处理工具
- 单位转换:`inches_to_pixels()`, `pixels_to_inches()`
- 图片适配:`apply_fit_mode()` - 支持 stretch/contain/cover/center 四种模式
- 画布创建:`create_canvas_with_background()` - 创建带背景色的画布
- **依赖**
- Pillow (PIL) - 用于高质量图片处理
- 使用 LANCZOS 重采样算法确保最佳质量
- **设计原则**
- 图片处理与渲染逻辑分离
- 支持 DPI 配置,灵活控制图片分辨率
- 所有图片操作返回 PIL Image 对象,便于后续处理
### 3. loaders/yaml_loader.py加载层
- **职责**YAML 文件加载和验证
@@ -109,6 +164,8 @@ yaml2pptx.py (入口)
- `_is_valid_color()` - 颜色格式验证工具函数
- `TextElement` - 文本元素dataclass + validate
- `ImageElement` - 图片元素dataclass + validate
- 新增字段:`fit` (适配模式), `background` (背景色)
- 支持四种适配模式stretch默认、contain、cover、center
- `ShapeElement` - 形状元素dataclass + validate
- `TableElement` - 表格元素dataclass + validate
- `create_element()` - 元素工厂函数
@@ -130,6 +187,10 @@ yaml2pptx.py (入口)
- `validators/resource.py` - 资源验证器
- `ResourceValidator` - 检查图片、模板文件存在性
- 验证模板文件结构
- `validators/image_config.py` - 图片配置验证器
- `validate_fit_value()` - 验证 fit 参数值
- `validate_background_color()` - 验证背景色格式
- `validate_dpi_value()` - 验证 DPI 值范围
- `validators/validator.py` - 主验证器
- `Validator` - 协调所有子验证器
- 集成元素级验证、几何验证、资源验证