Gallery

浏览多张图片或媒体资源。中文惯用名：画廊。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.gallery`
名称	Gallery
二级分类	媒体与内容（`media`）
用途	浏览多张图片或媒体资源
描述	中文惯用名：画廊。

预览

静态结构：缩略图栅格（grid-cols-{2|3|4}，aspect-square object-cover，caption 底部一行 truncate）；点击打开与 ImageViewer 共享的灯箱，追加上一张 / 下一张按钮（首末项隐藏对应按钮）与顶部序号指示（index / count），切换图片时自动复位缩放旋转。

DSL 结构

DslNode

{
  "type": "Gallery",
  "props": {
    "columns": 3,
    "items": [
      {
        "src": "https://example.com/photo-1.png",
        "alt": "照片 1",
        "caption": "办公区"
      },
      {
        "src": "https://example.com/photo-2.png",
        "alt": "照片 2",
        "caption": "会议室"
      }
    ]
  }
}

何时用

何时使用

浏览多张图片或媒体资源：相册、效果图集、活动现场图。
缩略图栅格 + 灯箱切换（前后翻页、序号指示）。

何时不用

单图查看：使用 ImageViewer。
图文混排的列表：使用 List / Card。

变体

变体	视觉形态	适用场景
三列（默认）	3 列方形缩略图	标准相册
两列 / 四列	更疏 / 更密栅格	大图展示 / 高密度浏览
带说明	缩略图下一行 caption	需要图注的图集

API 属性

属性	类型	默认值	说明
`items`	`GalleryItemData[]`	[]	图片列表：{ src, alt?, caption? }
`columns`	`2	3	4`
`onClose`	`event`	—	灯箱关闭事件（events.onClose）
`className / style`	`string / CSSProperties`	—	通用：根节点 class 合并 / 内联样式

使用规范

缩略图统一方形裁切（object-cover），原图在灯箱中完整查看。
caption 控制在一行内，长文案放详情页。
图片超过 20 张时加分页或「加载更多」，不一次渲染全部。

正例

✓ 活动现场图集：四列缩略图 + 灯箱翻页浏览。
✓ 效果图库：两列大图 + caption 标注方案名。

反例

✕ 用 Gallery 做头像墙（应使用 Avatar 组）。
✕ 缩略图直接链到原图新窗口（失去灯箱切换体验）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。