Image
展示图片及基础预览能力。中文惯用名：图片；放大缩放查看由媒体分类 ImageViewer 负责。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.image |
| 名称 | Image |
| 二级分类 | 数据展示（data-display） |
| 用途 | 展示图片及基础预览能力 |
| 描述 | 中文惯用名：图片；放大缩放查看由媒体分类 ImageViewer 负责。 |
预览
静态结构：Image 渲染单个 <img>（data-slot="image"，rounded-md，数值 width / height 透传为 HTML 属性，字符串长度走内联样式）。preview 缺省 true：图片带 cursor-zoom-in，点击经 vendored Dialog 打开预览弹层（sm:max-w-3xl 居中容器，大图 max-h-[80vh] object-contain，DialogTitle 以 sr-only 提供无障碍标题，取 alt 或「图片预览」）。src 为空或 onError 触发时渲染 fallback——缺省为 96px 灰色圆角占位块 + image 图标，可传 ReactNode 自定义；fallback 容器同样应用宽高样式。
DSL 结构
{
"type": "Image",
"props": {
"src": "https://example.com/report-cover.png",
"alt": "报表封面",
"width": 240,
"preview": true
}
}何时用
何时使用
- 内容区展示单张图片：封面、配图、证件照、商品图。
- 需要点击放大查看的基础预览（弹层居中大图，可关闭）。
- 需要明确尺寸约束与加载失败兜底（占位块 / 自定义 fallback）。
何时不用
- 多图浏览、缩放、旋转、切换等完整看图体验：使用 ImageViewer；Image 仅提供单图基础预览。
- 图片集合画廊：使用 Gallery / Carousel 类组件。
- 用户头像：使用 Avatar；列表内缩略图：使用 List 的 avatar 通道。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（可预览） | 圆角图片，点击经 Dialog 弹层放大 | 详情页、内容区需要看大图的配图 |
| preview=false 关闭预览 | 纯展示图片，无点击行为 | 装饰性图片、卡片封面等无需放大场景 |
| fallback 兜底 | 灰色占位块 + 图标（可自定义内容） | src 为空或加载失败的兜底呈现 |
| 固定尺寸 | width / height 约束（数值 px 或 CSS 长度） | 布局需要占位稳定、避免加载抖动的场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | — | 图片地址；为空时直接渲染 fallback |
alt | string | '' | 替代文本；同时作为预览弹层的无障碍标题 |
width | `number | string` | — |
height | `number | string` | — |
fallback | ReactNode | — | 加载失败或 src 为空时显示的内容；缺省为图标 + 灰色占位块 |
preview | boolean | true | 点击经 Dialog 弹层放大预览；false 时纯展示 |
className | string | — | 通用：根节点 class（与内置样式合并） |
style | CSSProperties | — | 通用：根节点内联样式（与 width / height 合并，style 优先） |
使用规范
- alt 必填语义化描述：既是加载失败 / 读屏的替代文本，也是预览弹层的无障碍标题；装饰图可留空但需确认无信息损失。
- 布局敏感区域显式给 width / height 占位，避免图片加载完成前后的布局抖动。
- preview 缺省开启；纯装饰或已有点击行为的图片显式关闭，避免双重交互。
- 预览仅为单图放大（Dialog 弹层、可关闭），不提供缩放 / 旋转 / 多图切换；这些需求引导至 ImageViewer。
- 失败兜底走 fallback：缺省占位块可接受时不必自定义；自定义 fallback 应保持与图片相同的尺寸约束。
正例
- ✓ 商品详情：width={320} 固定主图尺寸，保留默认 preview，alt 写商品名。
- ✓ 证件材料：加载失败用自定义 fallback 提示「图片加载失败，请刷新」，避免空白。
- ✓ 卡片封面：preview={false} 纯展示，点击行为交由卡片自身跳转。
反例
- ✕ 用 Image 拼凑多图画廊或期望缩放切换（应使用 ImageViewer / Gallery）。
- ✕ alt 留空或写「图片」等无信息文案，读屏与失败场景丢失上下文。
- ✕ 不给尺寸约束导致图片加载时内容区跳动，或 preview 图片上再叠加自定义点击冲突。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。