Files

lanyuanxiaoyao 19d6661381 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 模式

2026-03-04 10:29:21 +08:00

6.6 KiB

Raw Blame History

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

6.6 KiB Raw Blame History Unescape Escape