ImageGroup 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

统一组织多张图片的尺寸与排列，并提供成组预览，适合图库、附件和图片集合。

使用选择

用于在共享配置下组织图片。需要全屏查看、缩放或组间导航时配合 ImageViewer；布局与图片加载状态由公开 API 表达。

• 用 layout 选择组布局、size 统一图片尺寸。

• Image 子项自动加入媒体组；子项显式尺寸或 previewMode 优先于组默认配置。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Image, ImageGroup } from '@snowui-design-system/components';	import { ImageViewer } from '@snowui-design-system/components';	import cover01 from '@snowui-design-system/resource-base/assets/backgrounds/gradient-01-1024.jpg';	import cover02 from '@snowui-design-system/resource-base/assets/backgrounds/gradient-02-1024.jpg';	import cover03 from '@snowui-design-system/resource-base/assets/backgrounds/gradient-03-1024.jpg';	import cover04 from '@snowui-design-system/resource-base/assets/backgrounds/gradient-04-1024.jpg';</script> <ImageGroup size={80} style="flex-wrap: wrap; max-width: 100%;"><Image src={cover01} alt="SnowUI gradient resource 1"  /><Image src={cover02} alt="SnowUI gradient resource 2"  /><Image src={cover03} alt="SnowUI gradient resource 3"  /><Image src={cover04} alt="SnowUI gradient resource 4"  /></ImageGroup><ImageViewer />

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：复合管理布局。

• ImageGroup 的区域结构为 group root / media item collection / preview registration。

• 子项 Image 保持内禀原子布局；ImageGroup 只管理 row / column / grid 排列、统一尺寸上下文和 Viewer 注册。

• previewMode 是集合预览策略，不改变子项 Image 的内部布局模型。

• ImageGroup 不内嵌 ImageViewer；页面级 Viewer 作为独立复合管理组件消费组列表。

功能概览 (User)

• 统一组内图片尺寸

• 支持 row / column / grid 布局

• 固定默认间距 4px

• 与页面级 ImageViewer 配合承载多图预览索引

• 组内可自动收集 Image 媒体并向页面级 Viewer 提供组列表

2. 视觉规则

1. row / column / grid 三种布局的默认间距都固定为 4px，对应 var(--gap-1)，不提供 gap prop。

2. 不支持 stack 布局；布局职责仅限线性排列与网格排列。

3. 组内图片默认继承统一 size，子图片显式 size 优先。

4. grid 布局默认使用两列模板，避免在无额外列定义时视觉上退化为单行排列。

5. 组内 Image 会自动注册自己的 src/alt，供页面中的单一 ImageViewer 打开与切换。

6. 组列表快照在打开 Viewer 时直接按稳定引用传递，不再额外复制数组。

7. 组内媒体注册表使用原地 push/splice 维护，减少挂载/卸载时的短期数组分配。

8. previewMode 会作为组内 Image 的默认值向下透传；子图片显式 previewMode 优先。组与图片均省略时，页面存在共享 Viewer 即自动接入，否则回退 window。

3. 使用示例

<ImageGroup size={48}>    <Image src={Image01} />    <Image src={Image01} />    <Image /></ImageGroup>

<ImageGroup layout="grid" size={80}>    <Image src={Image01} />    <Image src={Image01} />    <Image src={Image01} />    <Image src={Image01} /></ImageGroup>

• 该组件当前不开放 gap prop；固定间距为 4px。

• 若后续扩展图库选择能力，应继续保持“尺寸统一由 Group 下发”的主链路。

• ImageGroup 不内嵌 ImageViewer；页面根部声明一个自动模式 Viewer 后，未显式设置 previewMode 的组会自动共享该服务。