---
name: component-image
description: Image 图片组件规范 — 本地路径约束、objectFit、生图/SVG边界与资源自检
---

# Image 组件规范

Image 是 slidep 中承载**位图 / 照片**的组件，继承 Box 所有属性。`src` 必须是**本地相对路径**，所有图片必须放在项目目录中。

## 基础用法

```jsx
<Image src="resources/images/hero.png" style={{ width: 400, borderRadius: 12 }} />
```

```jsx
<Image
    src="resources/images/ai_concept.png"
    style={{ width: '100%', height: '100%', objectFit: 'cover' }}
/>
```

## 属性速查

| 属性 | 说明 |
| :--- | :--- |
| `src` | **必填**。本地相对路径（相对项目根），必须先保存到 `resources/images/`。**严禁** `http://` / `https://` / `image://` 占位符 |
| `style.width` / `style.height` | 显示尺寸。建议与图片实际尺寸比例一致，避免拉伸变形 |
| `style.objectFit` | `'cover'`（裁切填满，默认推荐） / `'contain'`（完整显示，可能留白） / `'fill'`（强制拉伸，不推荐） |
| `style.clipPath` | 裁切形状（圆形 / 多边形 / SVG path） |
| `style.border` / `style.borderRadius` | 边框、圆角 |
| `style.opacity` | 透明度 |
| `style.filter` | CSS 滤镜（`blur` / `grayscale` / `brightness` 等） |

## 配图前置流程（先图后写，强制）

> 所有图片必须在写页面 JSX 之前完成获取、Read 核对、命名。严禁先写 JSX 占位后补图——会导致布局比例与图片不匹配。
> 配图策略参见 SKILL.md §配图获取策略：**取消搜图策略**。除用户材料图、文档抽取图、用户明确提供的品牌 / 产品 / 人物 / 场景图片外，配图只能来自 `ImageGen` 或 `<SVG>`。

### P0 · 材料图（已有可信图片）

用户上传材料、`scripts/extract.py` 抽取图、用户明确提供的品牌 / 产品 / 人物 / 场景图片可作为配图来源。使用前必须复制到 `resources/images/`，重命名为英文 / 数字 / 下划线文件名，并逐张 Read 核对内容、比例、清晰度。

### P1 · ImageGen（语义视觉默认路径）

以下场景必须优先调用 `ImageGen`，禁止直接用 SVG 糊弄：

- L1 主视觉、封面主图、章节过渡主图、左右图文页主图。
- 占内容区 ≥ 30% 的大面积背景、半屏图、一栏铺底图、卡片整体背景图。
- 城市、办公室、会议、工厂、实验室、校园、文旅、消费、产品使用、人物 / 群像 / 空间等具象场景。
- 摄影、插画、3D、国风、水墨、卡通、科技氛围等需要统一美术风格的画面。

调用 `ImageGen` 时，prompt 必须包含主体、场景、构图、风格、色彩、禁忌。同一 deck 复用同一组风格词，禁止摄影 / 插画 / 3D 混用。生图最多重试 2 次；仍不合格才允许 SVG 兜底，并在 `DESIGN.md` 配图清单记录失败原因。

**生图返回顺序常与 prompt 顺序错位**：必须逐张 Read 真实内容后再重命名映射到 DESIGN.md，禁止按时间戳盲映射。

### P2 · SVG（结构化 / 低语义元素）

`<SVG>` 只允许用于结构化、抽象化、低语义或品牌化元素：流程图、时间轴、矩阵、漏斗、架构图、关系网络、图表底图、巨型数字、趋势箭头、进度环、L3 角标、印章、页脚纹样、背景网格、抽象几何概念页。

禁止用几个圆、线、渐变块冒充城市、人物、会议、产品、校园、工厂等具象主视觉。禁止把 L3 角标或 200×70 小装饰当作 L1/L2。

### 引用

下载、复制或生成后必须立即 Read，确认四件事：

1. **内容正确**：图片主体与页面语义一致。
2. **比例可用**：能适配页面中的 L1 / L2 位置，不会裁掉关键主体。
3. **清晰度足够**：放到 PPT 中不糊。
4. **风格统一**：全篇图片属于同一视觉类型（摄影 / 插画 / 3D / 水墨等），不混用。

```jsx
<Image src="resources/images/team_collab.png" style={{ width: 400, height: 225 }} />
// 宽高比按实际图片比例（1920/1080 ≈ 16:9 → 400×225）
```

## 严禁事项

- **不得用通配符删除图片资源**（如 `rm -rf resources/images/*.png`）。替换图片时优先覆盖明确文件；确需删除时逐个指定具体路径。
- **图片不得自带页面需要精确控制的文字 / Logo**。需要精确文字时用干净背景图 + Slide 文本组件叠加。
- **不得直接引用在线 URL**（会导致构建产物中图片丢失）。
- **不得使用 `image://xxx` 占位符**。该占位符仅在未完成资源映射时由系统写入校验产物，Agent 不得主动产出。
- **正文页不得使用全屏背景图**。大图以独立组件形式出现（占 50% 宽 / 高），保留页面默认背景在四周可见。
- **不得用 SVG 几何背景代替必须生图的 L1/L2 主视觉**。只有 `ImageGen` 最多 2 次重试仍不合格时，才允许 SVG 兜底。

## 图片规划指引

- **配图率**：按项目 `DESIGN.md` 控制图文搭配密度；单页图片 / 图表数量不超过 3 个，总面积不超过内容区 60%。
- **风格一致性**：全篇要么摄影、要么插画、要么 3D 渲染，严禁混用；生图 prompt 应复用同一组风格词。
- **强制配图位置**：「左标题 + 右内容」必在右侧顶部或左侧标题下；「分栏」必须有一栏分配给图像。
- **图片清单必填**：项目 `DESIGN.md` 必须记录生成方式（material / ImageGen / SVG）、prompt 或 SVG 方案、本地文件名、真实内容、使用页面和是否核对。