# 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** 裁剪操作不损失图片质量