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 模式

tests/e2e/test_background_colors.yaml

@@ -0,0 +1,35 @@
+metadata:
+  title: "背景色测试"
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: text
+        content: "背景色支持测试"
+        box: [1, 0.5, 8, 0.8]
+        font:
+          size: 28
+          bold: true
+          align: center
+
+      # 白色背景
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [1, 1.5, 2.5, 2]
+        fit: contain
+        background: "#ffffff"
+
+      # 灰色背景
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [4, 1.5, 2.5, 2]
+        fit: contain
+        background: "#cccccc"
+
+      # 彩色背景
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [7, 1.5, 2.5, 2]
+        fit: center
+        background: "#e3f2fd"

tests/e2e/test_dpi_config.yaml

@@ -0,0 +1,20 @@
+metadata:
+  title: "DPI 配置测试"
+  size: "16:9"
+  dpi: 150
+
+slides:
+  - elements:
+      - type: text
+        content: "DPI: 150"
+        box: [1, 0.5, 8, 0.8]
+        font:
+          size: 28
+          bold: true
+          align: center
+
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [2, 1.5, 6, 3]
+        fit: contain
+        background: "#f5f5f5"

tests/e2e/test_fit_modes.yaml

@@ -0,0 +1,40 @@
+metadata:
+  title: "图片适配模式端到端测试"
+  size: "16:9"
+  dpi: 96
+
+slides:
+  # 测试所有 fit 模式
+  - elements:
+      - type: text
+        content: "图片适配模式测试"
+        box: [1, 0.5, 8, 0.8]
+        font:
+          size: 32
+          bold: true
+          align: center
+
+      # stretch 模式（默认）
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [0.5, 1.5, 2, 1.5]
+
+      # contain 模式
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [3, 1.5, 2, 1.5]
+        fit: contain
+        background: "#f0f0f0"
+
+      # cover 模式
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [5.5, 1.5, 2, 1.5]
+        fit: cover
+
+      # center 模式
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [8, 1.5, 2, 1.5]
+        fit: center
+        background: "#ffffff"

tests/e2e/test_invalid_params.yaml

@@ -0,0 +1,19 @@
+metadata:
+  title: "无效参数测试"
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      # 无效的 fit 值
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [1, 1, 3, 2]
+        fit: invalid_mode
+
+      # 无效的背景色
+      - type: image
+        src: "../fixtures/images/test_image.png"
+        box: [5, 1, 3, 2]
+        fit: contain
+        background: "not-a-color"

tests/integration/test_image_fit_modes.py

@@ -0,0 +1,304 @@
+"""
+图片适配模式集成测试
+
+测试图片 fit 模式在 PPTX 和 HTML 渲染中的完整流程。
+"""
+
+import pytest
+from pathlib import Path
+from PIL import Image
+from pptx import Presentation
+from core.presentation import Presentation as CorePresentation
+from renderers.pptx_renderer import PptxGenerator
+from renderers.html_renderer import HtmlRenderer
+
+
+@pytest.fixture
+def test_image_path(tmp_path):
+    """创建测试图片"""
+    img_path = tmp_path / "test_image.png"
+    # 创建 200x100 的测试图片
+    img = Image.new("RGB", (200, 100), color="red")
+    img.save(img_path)
+    return img_path
+
+
+@pytest.fixture
+def yaml_dir(tmp_path):
+    """创建临时 YAML 目录"""
+    return tmp_path
+
+
+class TestPptxImageFitModes:
+    """测试 PPTX 渲染器的图片适配模式"""
+
+    def test_stretch_mode(self, yaml_dir, test_image_path, tmp_path):
+        """测试 stretch 模式的 PPTX 渲染"""
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        # 加载并渲染
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        # 保存并验证
+        output_path = tmp_path / "stretch.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+        # 验证 PPTX 可以打开
+        pptx = Presentation(str(output_path))
+        assert len(pptx.slides) == 1
+
+    def test_contain_mode_larger_image(self, yaml_dir, tmp_path):
+        """测试 contain 模式（图片比 box 大）"""
+        # 创建 400x300 的大图片
+        img_path = yaml_dir / "large_image.png"
+        img = Image.new("RGB", (400, 300), color="blue")
+        img.save(img_path)
+
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{img_path.name}"
+        box: [1, 1, 3, 2]
+        fit: contain
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        output_path = tmp_path / "contain_large.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+    def test_contain_mode_smaller_image(self, yaml_dir, tmp_path):
+        """测试 contain 模式（图片比 box 小）"""
+        # 创建 50x50 的小图片
+        img_path = yaml_dir / "small_image.png"
+        img = Image.new("RGB", (50, 50), color="green")
+        img.save(img_path)
+
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{img_path.name}"
+        box: [1, 1, 4, 3]
+        fit: contain
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        output_path = tmp_path / "contain_small.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+    def test_contain_mode_with_background(self, yaml_dir, test_image_path, tmp_path):
+        """测试 contain 模式（带背景色）"""
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: contain
+        background: "#f0f0f0"
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        output_path = tmp_path / "contain_bg.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+    def test_cover_mode(self, yaml_dir, test_image_path, tmp_path):
+        """测试 cover 模式"""
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: cover
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        output_path = tmp_path / "cover.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+    def test_center_mode_with_background(self, yaml_dir, test_image_path, tmp_path):
+        """测试 center 模式（带背景色）"""
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: center
+        background: "#ffffff"
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        pres = CorePresentation(str(yaml_path))
+        gen = PptxGenerator(size='16:9', dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            gen.add_slide(rendered, base_path=yaml_dir)
+
+        output_path = tmp_path / "center_bg.pptx"
+        gen.save(output_path)
+        assert output_path.exists()
+
+    def test_different_dpi_values(self, yaml_dir, test_image_path, tmp_path):
+        """测试不同 DPI 配置"""
+        for dpi in [72, 96, 150, 300]:
+            yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: {dpi}
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: contain
+"""
+            yaml_path = yaml_dir / f"test_dpi_{dpi}.yaml"
+            yaml_path.write_text(yaml_content)
+
+            pres = CorePresentation(str(yaml_path))
+            gen = PptxGenerator(size='16:9', dpi=dpi)
+
+            for slide_data in pres.data.get('slides', []):
+                rendered = pres.render_slide(slide_data)
+                gen.add_slide(rendered, base_path=yaml_dir)
+
+            output_path = tmp_path / f"dpi_{dpi}.pptx"
+            gen.save(output_path)
+            assert output_path.exists()
+
+
+class TestHtmlImageFitModes:
+    """测试 HTML 渲染器的图片适配模式"""
+
+    def test_html_fit_modes(self, yaml_dir, test_image_path):
+        """测试 HTML 渲染器的四种 fit 模式"""
+        for fit_mode in ['stretch', 'contain', 'cover', 'center']:
+            yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: {fit_mode}
+"""
+            yaml_path = yaml_dir / f"test_{fit_mode}.yaml"
+            yaml_path.write_text(yaml_content)
+
+            pres = CorePresentation(str(yaml_path))
+            renderer = HtmlRenderer(dpi=96)
+
+            for slide_data in pres.data.get('slides', []):
+                rendered = pres.render_slide(slide_data)
+                html = renderer.render_slide(rendered, 0, base_path=yaml_dir)
+                # 验证 HTML 包含图片元素
+                assert '<img' in html or 'background-image' in html
+
+    def test_html_background_color(self, yaml_dir, test_image_path):
+        """测试 HTML 渲染器的背景色支持"""
+        yaml_content = f"""
+metadata:
+  size: "16:9"
+  dpi: 96
+
+slides:
+  - elements:
+      - type: image
+        src: "{test_image_path.name}"
+        box: [1, 1, 4, 3]
+        fit: contain
+        background: "#f0f0f0"
+"""
+        yaml_path = yaml_dir / "test.yaml"
+        yaml_path.write_text(yaml_content)
+
+        pres = CorePresentation(str(yaml_path))
+        renderer = HtmlRenderer(dpi=96)
+
+        for slide_data in pres.data.get('slides', []):
+            rendered = pres.render_slide(slide_data)
+            html = renderer.render_slide(rendered, 0, base_path=yaml_dir)
+            # 验证 HTML 包含背景色
+            assert '#f0f0f0' in html or 'background-color' in html

tests/unit/test_elements.py

@@ -89,6 +89,19 @@ class TestImageElement:
         assert elem.type == 'image'
         assert elem.src == "test.png"
         assert elem.box == [1, 1, 4, 3]
+        assert elem.fit is None
+        assert elem.background is None
+
+    def test_create_with_fit_and_background(self):
+        """测试创建带 fit 和 background 的 ImageElement"""
+        elem = ImageElement(
+            src="test.png",
+            box=[1, 1, 4, 3],
+            fit="contain",
+            background="#ffffff"
+        )
+        assert elem.fit == "contain"
+        assert elem.background == "#ffffff"
 
     def test_empty_src_raises_error(self):
         """测试空 src 会引发错误"""

tests/unit/test_image_utils.py

@@ -0,0 +1,120 @@
+"""
+单元测试：图片处理工具函数
+
+测试 utils/image_utils.py 中的图片处理函数。
+"""
+
+import pytest
+from PIL import Image
+from utils.image_utils import (
+    inches_to_pixels,
+    pixels_to_inches,
+    apply_fit_mode,
+    create_canvas_with_background,
+)
+
+
+class TestUnitConversion:
+    """测试单位转换函数"""
+
+    def test_inches_to_pixels_default_dpi(self):
+        """测试英寸转像素（默认 96 DPI）"""
+        assert inches_to_pixels(1) == 96
+        assert inches_to_pixels(2) == 192
+        assert inches_to_pixels(0.5) == 48
+
+    def test_inches_to_pixels_custom_dpi(self):
+        """测试英寸转像素（自定义 DPI）"""
+        assert inches_to_pixels(1, dpi=72) == 72
+        assert inches_to_pixels(2, dpi=150) == 300
+        assert inches_to_pixels(0.5, dpi=300) == 150
+
+    def test_pixels_to_inches_default_dpi(self):
+        """测试像素转英寸（默认 96 DPI）"""
+        assert pixels_to_inches(96) == 1.0
+        assert pixels_to_inches(192) == 2.0
+        assert pixels_to_inches(48) == 0.5
+
+    def test_pixels_to_inches_custom_dpi(self):
+        """测试像素转英寸（自定义 DPI）"""
+        assert pixels_to_inches(72, dpi=72) == 1.0
+        assert pixels_to_inches(300, dpi=150) == 2.0
+
+
+class TestApplyFitMode:
+    """测试图片适配模式函数"""
+
+    @pytest.fixture
+    def test_image(self):
+        """创建测试图片（100x100）"""
+        return Image.new("RGB", (100, 100), color="red")
+
+    def test_stretch_mode(self, test_image):
+        """测试 stretch 模式"""
+        result = apply_fit_mode(test_image, (200, 150), "stretch")
+        assert result.size == (200, 150)
+
+    def test_contain_mode_wider_box(self, test_image):
+        """测试 contain 模式（box 更宽）"""
+        result = apply_fit_mode(test_image, (200, 100), "contain")
+        # 图片应该适配到高度，宽度保持比例
+        assert result.size == (100, 100)
+
+    def test_contain_mode_taller_box(self, test_image):
+        """测试 contain 模式（box 更高）"""
+        result = apply_fit_mode(test_image, (100, 200), "contain")
+        # 图片应该适配到宽度，高度保持比例
+        assert result.size == (100, 100)
+
+    def test_cover_mode_wider_box(self, test_image):
+        """测试 cover 模式（box 更宽）"""
+        result = apply_fit_mode(test_image, (200, 100), "cover")
+        # 图片应该覆盖整个 box
+        assert result.size == (200, 100)
+
+    def test_cover_mode_taller_box(self, test_image):
+        """测试 cover 模式（box 更高）"""
+        result = apply_fit_mode(test_image, (100, 200), "cover")
+        # 图片应该覆盖整个 box
+        assert result.size == (100, 200)
+
+    def test_center_mode(self, test_image):
+        """测试 center 模式"""
+        result = apply_fit_mode(test_image, (200, 150), "center")
+        # center 模式保持原始尺寸
+        assert result.size == (100, 100)
+
+    def test_invalid_mode(self, test_image):
+        """测试无效的 fit 模式"""
+        with pytest.raises(ValueError, match="不支持的 fit 模式"):
+            apply_fit_mode(test_image, (200, 150), "invalid")
+
+
+class TestCreateCanvas:
+    """测试画布创建函数"""
+
+    def test_create_canvas_with_white_background(self):
+        """测试创建白色背景画布"""
+        canvas = create_canvas_with_background((200, 150), "#ffffff")
+        assert canvas.size == (200, 150)
+        assert canvas.mode == "RGB"
+        # 检查中心像素是白色
+        assert canvas.getpixel((100, 75)) == (255, 255, 255)
+
+    def test_create_canvas_with_colored_background(self):
+        """测试创建彩色背景画布"""
+        canvas = create_canvas_with_background((200, 150), "#ff0000")
+        assert canvas.size == (200, 150)
+        # 检查中心像素是红色
+        assert canvas.getpixel((100, 75)) == (255, 0, 0)
+
+    def test_create_canvas_with_short_hex(self):
+        """测试创建画布（短格式十六进制颜色）"""
+        canvas = create_canvas_with_background((100, 100), "#f00")
+        # 检查中心像素是红色
+        assert canvas.getpixel((50, 50)) == (255, 0, 0)
+
+    def test_create_canvas_with_invalid_color(self):
+        """测试无效颜色格式"""
+        with pytest.raises(ValueError, match="无效的颜色格式"):
+            create_canvas_with_background((100, 100), "invalid")

tests/unit/test_validators/test_image_config.py

@@ -0,0 +1,136 @@
+"""
+单元测试：图片配置验证器
+
+测试 validators/image_config.py 中的验证函数。
+"""
+
+import pytest
+from validators.image_config import (
+    validate_fit_value,
+    validate_background_color,
+    validate_dpi_value,
+)
+
+
+class TestValidateFitValue:
+    """测试 fit 值验证"""
+
+    def test_valid_fit_values(self):
+        """测试有效的 fit 值"""
+        assert validate_fit_value("stretch") == []
+        assert validate_fit_value("contain") == []
+        assert validate_fit_value("cover") == []
+        assert validate_fit_value("center") == []
+
+    def test_none_fit_value(self):
+        """测试 None 值（默认）"""
+        # None 是无效的，应该返回错误
+        issues = validate_fit_value(None)
+        assert len(issues) > 0
+
+    def test_invalid_fit_value(self):
+        """测试无效的 fit 值"""
+        issues = validate_fit_value("invalid")
+        assert len(issues) > 0
+        assert issues[0].level == "ERROR"
+
+        issues = validate_fit_value("fill")
+        assert len(issues) > 0
+
+        issues = validate_fit_value("scale")
+        assert len(issues) > 0
+
+    def test_case_sensitive(self):
+        """测试大小写敏感"""
+        issues = validate_fit_value("STRETCH")
+        assert len(issues) > 0
+
+        issues = validate_fit_value("Contain")
+        assert len(issues) > 0
+
+
+class TestValidateBackgroundColor:
+    """测试背景色验证"""
+
+    def test_valid_hex_colors(self):
+        """测试有效的十六进制颜色"""
+        assert validate_background_color("#ffffff") == []
+        assert validate_background_color("#000000") == []
+        assert validate_background_color("#ff0000") == []
+        assert validate_background_color("#4a90e2") == []
+
+    def test_valid_short_hex_colors(self):
+        """测试有效的短格式十六进制颜色"""
+        assert validate_background_color("#fff") == []
+        assert validate_background_color("#000") == []
+        assert validate_background_color("#f00") == []
+
+    def test_none_background(self):
+        """测试 None 值（透明）"""
+        # None 会导致 TypeError，应该返回错误
+        issues = validate_background_color(None)
+        assert len(issues) > 0
+
+    def test_invalid_colors(self):
+        """测试无效的颜色格式"""
+        issues = validate_background_color("white")
+        assert len(issues) > 0
+
+        issues = validate_background_color("rgb(255,255,255)")
+        assert len(issues) > 0
+
+        issues = validate_background_color("#gggggg")
+        assert len(issues) > 0
+
+        issues = validate_background_color("#ff")
+        assert len(issues) > 0
+
+        issues = validate_background_color("ffffff")
+        assert len(issues) > 0
+
+
+class TestValidateDpiValue:
+    """测试 DPI 值验证"""
+
+    def test_valid_dpi_values(self):
+        """测试有效的 DPI 值"""
+        assert validate_dpi_value(72) == []
+        assert validate_dpi_value(96) == []
+        assert validate_dpi_value(150) == []
+        assert validate_dpi_value(300) == []
+
+    def test_boundary_dpi_values(self):
+        """测试边界 DPI 值"""
+        # 1 和 1200 超出建议范围，会返回 WARNING
+        issues = validate_dpi_value(1)
+        assert len(issues) > 0
+        assert issues[0].level == "WARNING"
+
+        issues = validate_dpi_value(1200)
+        assert len(issues) > 0
+        assert issues[0].level == "WARNING"
+
+    def test_invalid_dpi_values(self):
+        """测试无效的 DPI 值"""
+        # 0 和负数会返回 WARNING
+        issues = validate_dpi_value(0)
+        assert len(issues) > 0
+
+        issues = validate_dpi_value(-1)
+        assert len(issues) > 0
+
+        issues = validate_dpi_value(1201)
+        assert len(issues) > 0
+
+        issues = validate_dpi_value(2000)
+        assert len(issues) > 0
+
+    def test_non_integer_dpi(self):
+        """测试非整数 DPI 值"""
+        # 浮点数 DPI 可能被接受（取决于实现）
+        # 字符串和 None 应该返回错误
+        issues = validate_dpi_value("96")
+        assert len(issues) > 0
+
+        issues = validate_dpi_value(None)
+        assert len(issues) > 0