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 模式
202 lines
6.6 KiB
Markdown
202 lines
6.6 KiB
Markdown
# Image Fit Modes
|
||
|
||
## Purpose
|
||
|
||
图片适配模式能力为图片元素提供多种适配策略，允许用户控制图片在指定区域内的显示方式，包括拉伸、保持比例、填充裁剪和居中显示。同时支持 DPI 配置和背景色填充，满足不同场景的视觉需求。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 系统必须支持图片 fit 参数
|
||
|
||
系统 SHALL 支持图片元素的 `fit` 参数，允许用户指定图片适配模式。
|
||
|
||
#### Scenario: fit 参数支持四种模式
|
||
|
||
- **WHEN** 图片元素定义了 `fit` 参数
|
||
- **THEN** 系统支持 `stretch`、`contain`、`cover`、`center` 四种模式
|
||
|
||
#### Scenario: fit 参数默认值为 stretch
|
||
|
||
- **WHEN** 图片元素未指定 `fit` 参数
|
||
- **THEN** 系统使用 `stretch` 模式（向后兼容）
|
||
|
||
#### Scenario: fit 参数值无效时报错
|
||
|
||
- **WHEN** `fit` 参数值不是四种有效模式之一
|
||
- **THEN** 系统抛出 ERROR，并列出有效值（stretch、contain、cover、center）
|
||
|
||
### Requirement: 系统必须支持 stretch 模式
|
||
|
||
系统 SHALL 在 `stretch` 模式下将图片强制缩放到 box 指定的尺寸，不考虑宽高比。
|
||
|
||
#### Scenario: stretch 模式拉伸图片
|
||
|
||
- **WHEN** 图片元素定义了 `fit: stretch` 或未指定 `fit`
|
||
- **THEN** 系统将图片拉伸到 box 的宽高尺寸
|
||
- **AND** 图片可能变形
|
||
|
||
#### Scenario: stretch 模式不考虑背景色
|
||
|
||
- **WHEN** 图片使用 `fit: stretch` 并指定了 `background`
|
||
- **THEN** 背景色参数被忽略（无留白区域）
|
||
|
||
### Requirement: 系统必须支持 contain 模式
|
||
|
||
系统 SHALL 在 `contain` 模式下保持图片宽高比，完整显示图片在 box 内，可能有留白。
|
||
|
||
#### Scenario: contain 模式保持宽高比
|
||
|
||
- **WHEN** 图片元素定义了 `fit: contain`
|
||
- **THEN** 系统缩放图片使其完整显示在 box 内
|
||
- **AND** 保持原始宽高比
|
||
- **AND** 图片尺寸不超过 box 尺寸
|
||
|
||
#### Scenario: contain 模式图片居中
|
||
|
||
- **WHEN** 图片使用 `fit: contain` 且小于 box 尺寸
|
||
- **THEN** 系统将图片居中显示在 box 内
|
||
|
||
#### Scenario: contain 模式支持背景色
|
||
|
||
- **WHEN** 图片使用 `fit: contain` 并指定了 `background`
|
||
- **THEN** 系统用指定颜色填充 box 内的留白区域
|
||
|
||
#### Scenario: contain 模式图片比 box 大
|
||
|
||
- **WHEN** 图片原始尺寸大于 box 尺寸
|
||
- **THEN** 系统等比缩小图片使其完整显示在 box 内
|
||
|
||
#### Scenario: contain 模式图片比 box 小
|
||
|
||
- **WHEN** 图片原始尺寸小于 box 尺寸
|
||
- **THEN** 系统保持原始尺寸，居中显示在 box 内
|
||
|
||
### Requirement: 系统必须支持 cover 模式
|
||
|
||
系统 SHALL 在 `cover` 模式下保持图片宽高比，填充整个 box，裁剪超出部分。
|
||
|
||
#### Scenario: cover 模式保持宽高比
|
||
|
||
- **WHEN** 图片元素定义了 `fit: cover`
|
||
- **THEN** 系统缩放图片使其填满 box
|
||
- **AND** 保持原始宽高比
|
||
- **AND** 裁剪超出 box 的部分
|
||
|
||
#### Scenario: cover 模式图片居中裁剪
|
||
|
||
- **WHEN** 图片使用 `fit: cover` 且需要裁剪
|
||
- **THEN** 系统从图片中心进行裁剪
|
||
|
||
#### Scenario: cover 模式不考虑背景色
|
||
|
||
- **WHEN** 图片使用 `fit: cover` 并指定了 `background`
|
||
- **THEN** 背景色参数被忽略（无留白区域）
|
||
|
||
#### Scenario: cover 模式图片比 box 大
|
||
|
||
- **WHEN** 图片原始尺寸大于 box 尺寸
|
||
- **THEN** 系统等比缩小图片并裁剪超出部分
|
||
|
||
#### Scenario: cover 模式图片比 box 小
|
||
|
||
- **WHEN** 图片原始尺寸小于 box 尺寸
|
||
- **THEN** 系统等比放大图片并裁剪超出部分
|
||
|
||
### Requirement: 系统必须支持 center 模式
|
||
|
||
系统 SHALL 在 `center` 模式下按原始尺寸居中显示图片，不缩放，超出 box 的部分被裁剪。
|
||
|
||
#### Scenario: center 模式不缩放图片
|
||
|
||
- **WHEN** 图片元素定义了 `fit: center`
|
||
- **THEN** 系统保持图片原始尺寸，不进行缩放
|
||
|
||
#### Scenario: center 模式图片居中
|
||
|
||
- **WHEN** 图片使用 `fit: center`
|
||
- **THEN** 系统将图片居中显示在 box 内
|
||
|
||
#### Scenario: center 模式裁剪超出部分
|
||
|
||
- **WHEN** 图片原始尺寸大于 box 尺寸
|
||
- **THEN** 系统裁剪超出 box 的部分（从中心裁剪）
|
||
|
||
#### Scenario: center 模式支持背景色
|
||
|
||
- **WHEN** 图片使用 `fit: center` 并指定了 `background`
|
||
- **THEN** 系统用指定颜色填充 box 内的留白区域
|
||
|
||
### Requirement: 系统必须支持 background 参数
|
||
|
||
系统 SHALL 支持图片元素的 `background` 参数，允许用户指定留白区域的填充颜色。
|
||
|
||
#### Scenario: background 参数默认透明
|
||
|
||
- **WHEN** 图片元素未指定 `background` 参数
|
||
- **THEN** 留白区域保持透明
|
||
|
||
#### Scenario: background 参数支持纯色
|
||
|
||
- **WHEN** 图片元素指定了 `background: "#ff0000"`
|
||
- **THEN** 系统使用指定颜色填充留白区域
|
||
|
||
#### Scenario: background 参数不支持渐变
|
||
|
||
- **WHEN** 图片元素指定了渐变色（如 `"linear-gradient(...)"`）
|
||
- **THEN** 系统抛出 ERROR，提示仅支持纯色
|
||
|
||
#### Scenario: background 参数颜色格式验证
|
||
|
||
- **WHEN** `background` 值不是有效的颜色格式
|
||
- **THEN** 系统抛出 ERROR，提示颜色格式应为 #RRGGBB 或 #RGB
|
||
|
||
### Requirement: 系统必须支持文档级 DPI 配置
|
||
|
||
系统 SHALL 支持在 `metadata.dpi` 中配置 DPI 值，用于像素与英寸的转换。
|
||
|
||
#### Scenario: DPI 默认值为 96
|
||
|
||
- **WHEN** metadata 未指定 `dpi` 参数
|
||
- **THEN** 系统使用默认值 96
|
||
|
||
#### Scenario: DPI 配置影响所有图片
|
||
|
||
- **WHEN** metadata 指定了 `dpi: 120`
|
||
- **THEN** 系统使用该值进行所有图片的像素与英寸转换
|
||
|
||
#### Scenario: DPI 值验证
|
||
|
||
- **WHEN** `dpi` 值超出合理范围（如小于 72 或大于 300）
|
||
- **THEN** 系统发出 WARNING，提示 DPI 值可能不合适
|
||
|
||
### Requirement: 系统必须在图片处理失败时抛出错误
|
||
|
||
系统 SHALL 在图片处理失败时抛出 ERROR 级别错误，不提供降级方案。
|
||
|
||
#### Scenario: 损坏的图片文件
|
||
|
||
- **WHEN** Pillow 无法读取图片文件（文件损坏或格式不支持）
|
||
- **THEN** 系统抛出 ERROR，明确指出图片文件问题
|
||
- **AND** 不降级到其他模式
|
||
|
||
#### Scenario: 图片处理异常
|
||
|
||
- **WHEN** Pillow 处理图片时发生异常（如内存不足）
|
||
- **THEN** 系统抛出 ERROR，包含异常信息
|
||
- **AND** 不降级到其他模式
|
||
|
||
### Requirement: 系统必须使用最高质量的图片处理算法
|
||
|
||
系统 SHALL 使用 Pillow 的最高质量重采样算法（LANCZOS）进行图片缩放。
|
||
|
||
#### Scenario: 图片缩放使用 LANCZOS
|
||
|
||
- **WHEN** 系统需要缩放图片（contain、cover 模式）
|
||
- **THEN** 使用 Pillow 的 LANCZOS 重采样算法
|
||
- **AND** 不向用户暴露质量配置选项
|
||
|
||
#### Scenario: 图片裁剪保持质量
|
||
|
||
- **WHEN** 系统需要裁剪图片（cover、center 模式）
|
||
- **THEN** 裁剪操作不损失图片质量
|