ImageViewer
放大、缩放和切换单张图片。中文惯用名：图片查看器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.image-viewer |
| 名称 | ImageViewer |
| 二级分类 | 媒体与内容（media） |
| 用途 | 放大、缩放和切换单张图片 |
| 描述 | 中文惯用名：图片查看器。 |
预览
静态结构：行内图片 <img data-slot="image-viewer-img">（preview 时 cursor-zoom-in）；点击打开灯箱 <div data-slot="image-lightbox">（fixed inset-0，bg-(--overlay-background) 遮罩）——居中图片（scale / rotate 变换，0.5x~4x，步进 0.5；旋转步进 -90°）+ 底部工具条（放大 / 缩小 / 旋转 / 复位 / 关闭）+ 遮罩点击与 Esc 关闭，关闭触发 onClose。Gallery 复用同一灯箱（追加前后切换与序号）。
DSL 结构
{
"type": "ImageViewer",
"props": {
"src": "https://example.com/diagram.png",
"alt": "架构图",
"preview": true
}
}何时用
何时使用
- 单张图片需要放大查看细节：设计稿、截图、证件照、图表。
- 需要缩放 / 旋转 / 复位的沉浸式查看（灯箱）。
何时不用
- 纯展示不需要查看交互：使用数据展示分类的 Image。
- 多图浏览与切换：使用 Gallery。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 行内 + 灯箱 | 缩略图点击放大 | 详情页附图、设计稿查看 |
| 纯展示 | preview=false | 只读展示但保留语义 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | — | 图片地址 |
alt | string | — | 替代文本 |
preview | boolean | true | 是否允许点击放大查看 |
onClose | event | — | 灯箱关闭事件（events.onClose） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- alt 必填，描述图片内容而非文件名。
- 灯箱缩放范围 0.5x~4x，超出业务需求时自行裁剪图源而非放宽上限。
- 多图场景改用 Gallery，不并列多个 ImageViewer。
正例
- ✓ 设计评审页：设计稿缩略图点击放大，灯箱内缩放查看标注细节。
- ✓ 证件审核：证件照放大 + 旋转校正方向后核对。
反例
- ✕ 用 ImageViewer 做图片列表（应使用 Gallery）。
- ✕ 在行内图上叠加自定义操作按钮（交互应集中在灯箱工具条）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。