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

@@ -0,0 +1,44 @@
# 图片适配模式支持
## Why
当前图片元素渲染仅支持简单的拉伸模式,图片会被强制缩放到 box 指定的尺寸,导致图片变形或宽高比失真。实际使用中,用户需要保持图片宽高比、居中显示、填充裁剪等多种适配模式,以满足不同场景的视觉需求。
## What Changes
- 新增图片 `fit` 参数,支持四种适配模式:`stretch`(拉伸)、`contain`(包含)、`cover`(覆盖)、`center`(居中)
- 新增图片 `background` 参数,支持指定留白区域的填充颜色(默认透明)
- 新增文档级 `dpi` 配置(`metadata.dpi`),用于像素与英寸的转换,默认值为 96
- 引入 Pillow 库进行图片处理,利用其 ImageOps 模块实现各种适配模式
- 保持向后兼容:未指定 `fit` 时默认使用 `stretch` 模式(当前行为)
## Capabilities
### New Capabilities
- `image-fit-modes`: 图片元素适配模式处理,支持 stretch、contain、cover、center 四种模式,以及背景色填充和 DPI 配置
### Modified Capabilities
- `element-rendering`: 扩展图片元素渲染能力,新增 `fit``background` 参数支持
- `html-rendering`: 同步扩展 HTML 预览的图片渲染能力,支持 `fit``background` 参数,使用 CSS object-fit 实现
## Impact
### 依赖变更
- 新增 Pillow 依赖(不指定版本号,使用最新版)
### 代码变更
- `core/elements.py`: ImageElement 新增 `fit``background` 字段
- `renderers/pptx_renderer.py`: 重写 `_render_image()` 方法,集成 Pillow 图片处理
- `renderers/html_renderer.py`: 更新 `_render_image()` 方法,使用 CSS object-fit 实现适配模式
- `validators/`: 新增图片参数验证器fit 值校验、background 颜色校验)
- `utils/image_utils.py`: 新增图片处理工具模块(像素转换、尺寸计算、居中定位)
### API 变更
- YAML 语法扩展:
- `metadata` 层级新增可选的 `dpi` 字段
- 图片元素新增可选的 `fit` 字段
- 图片元素新增可选的 `background` 字段
### 文档变更
- `README.md`: 新增图片适配模式使用说明和示例
- `README_DEV.md`: 新增图片处理架构说明