Album 相册

九宫格图片组：单图大图、多图网格、超出数量折叠为剩余数量格；点击图片打开内置全屏画廊（横滑翻页 + 页码胶囊 + 描述条）。适合动态配图、评价晒单、商品详情图组等嵌入内容流的图片组展示。

平台兼容性

App(Android/iOS)	Web	微信小程序	鸿蒙
✓	✓	✓	✓

基本使用

urls 传图片地址数组；一张图走单图形态（single-size 边长），多张走网格（默认每行 3 张等分）：

<n-album :urls="['https://cdn.example.com/a.jpg', 'https://cdn.example.com/b.jpg', 'https://cdn.example.com/c.jpg']" />

点击任意图片会打开全屏画廊（横滑翻页、页码胶囊）；不需要点击预览时设 preview-full-image 为 false：

<n-album :urls="urls" :preview-full-image="false" />

对象数组

urls 为对象数组时，图片地址取 key-name 指定的字段（默认 src）；画廊描述条文本取 descr-key 指定的字段（默认 descr，缺失该字段的图片不显示描述条）：

<n-album :urls="list" key-name="pic" descr-key="caption" />

const list = [
	{ pic: '/static/a.jpg', caption: '第一张的说明文字' },
	{ pic: '/static/b.jpg' }
];

数量与布局

max-count 限制最多展示的图片数，超出部分折叠到最后一位（半透明深色格 + 剩余数量），show-more 关闭后直接截断；点击数量格从最后一张可见图继续预览：

<n-album :urls="urls" :max-count="4" :show-more="false" />

row-count 大于 0 时按行数等分布局（multiple-size 不参与）；设为 0 关闭等分，改按 multiple-size 定尺寸自由换行。space 控制格间距：

<n-album :urls="urls" :row-count="2" />
<n-album :urls="urls" :row-count="0" multiple-size="120rpx" space="10" />

全屏画廊

画廊翻页时发送 change（载荷 {index}），点击图片关闭时发送 close；也可以用实例方法程序化开关（先声明有类型的 ref）：

<n-album ref="album" :urls="urls" @change="onChange" @close="onClose" />

// 打开画廊并定位到第 3 张（下标从 0 起，越界自动钳制）；urls 为空时忽略
album.value?.openPreview(2);
// 程序化关闭（不发 close 事件）
album.value?.closePreview();

图文对齐

相册宽度由容器决定；需要让相邻文字与图片组对齐时，监听 album-width 取实测宽度（布局就绪与容器尺寸变化时触发）：

<n-album :urls="urls" @album-width="onAlbumWidth" />
<text :style="'width:' + albumWidth + 'px'">与相册等宽的说明文字</text>

API

Props

属性	说明	类型	默认值
urls	图片列表：字符串数组（直接作地址），或对象数组（地址取 item[keyName]、描述取 item[descrKey]）	string[] | UTSJSONObject[]	[]
key-name	urls 为对象数组时，图片地址的属性名	string	src
descr-key	urls 为对象数组时，画廊描述条文本的属性名；缺失该字段的图片不显示描述条	string	descr
single-size	单图时的边长（正方形，宽高同值，超出相册宽度时收缩到容器宽）；数字 px 或 px/rpx 字符串	string | number	180
multiple-size	多图时每格边长（正方形）；row-count 大于 0 的等分布局下不参与布局	string | number	70
space	多图格与格的间隔（横向与纵向同值）；数字 px 或 px/rpx 字符串	string | number	6
single-mode	单图的裁剪缩放模式（image 原生 mode）	string	scaleToFill
multiple-mode	多图的裁剪缩放模式（image 原生 mode）	string	aspectFill
max-count	最多展示的图片数量，超出部分折叠到最后一位（show-more 控制是否显示剩余数量）；0 = 不限制	number	9
row-count	每行图片数量：大于 0 时等分布局（multiple-size 不参与）；0 = 关闭等分，按 multiple-size 定尺寸自由换行	number	3
show-more	超出 max-count 时最后一位显示剩余数量（半透明深色格 + 白字）；点击它从最后一张可见图继续预览	boolean	true
preview-full-image	点击九宫格图片是否打开全屏画廊；false 时点击无响应	boolean	true
z-index	全屏画廊层级（弹层族语义内：遮罩 1000 之上），与弹层同用时按需调大	number	1001
safe-area	画廊描述条是否垫底部安全区（手势条机型留出小白条高度）	boolean	true
ellipsis	画廊描述文本超出宽度时省略为单行；false 多行完整显示	boolean	false
custom-class	挂到根节点的额外 class（类须定义在组件样式表内）	string	—
custom-style	根节点行内样式，如 margin:12px；拼接在内部样式之后	string	—

Events

事件名	说明	回调参数
album-width	相册容器实测宽度就绪或变化时触发（图文对齐用）	{ width: number }
change	画廊翻页时触发（原生滑切；程序定位不发）	{ index: number }
close	点击画廊图片关闭时触发（程序化 closePreview 不发）	—

Methods

方法名	说明	参数
openPreview	打开全屏画廊并定位到指定下标（越界钳制、负值归 0）；urls 为空时忽略	(index?: number)
closePreview	程序化关闭全屏画廊（不发 close 事件）	—

Slots

无插槽。

实现说明（与参考实现的机制对照）

参考做法	本库做法	分歧理由
全屏预览调 uni.previewImage（原生接口，外观不可定制）	内置自绘全屏画廊（swiper 翻页 + 页码胶囊 + 描述条）	preview-full-image 的 API 语义不变（点击可预览的开关），参考接口未暴露任何预览层配置，换实现不损失 API 面；系统预览已由图片组件承担，本组件的差异化价值在可定制画廊（页码、描述条）
画廊独立受控用法（show / current 属性驱动显隐与定位）	方法通道 openPreview(index) / closePreview()	瞬时交互层的方法式打开（裁剪器同款）；翻页回执 change 与点击关闭 close 保留
画廊关闭事件名为 hide（通知使用方把 show 置 false）	改名 close	受控通道换成方法后，hide 的"通知收起"职责由组件内部消化，事件语义收敛为"画廊被点击关闭"
key-name 默认值未给（文档标 -）	默认 "src"	参考画廊组件 srcKey 的明文默认值，两参考源取同惯例
row-count 默认 3，文档写明设置后 multiple-size 无效	row-count = 0 作为关闭等分的通道	默认 3 使 multiple-size 恒无生效场景（历史包袱）；0 = 按 multiple-size 定尺寸自由换行，让两个尺寸属性各有所用
max-count 折叠格只说"显示剩余图片数量"	半透明深色格 + 白字，点击从最后一张可见图继续预览	参考未定义视觉与点击行为；深色融入图片网格语境（不随主题），点击行为与浏览习惯一致
画廊显隐无过渡（display 直接切换）	固定短淡入淡出（无属性暴露）	弹层族全部带过渡，硬切观感突兀；固定时长不增加属性面

注意事项

• 微信端画廊内图片建议使用网络路径；本地代码包路径在小程序图片组件中受包体积限制
• urls 为空时组件渲染空容器（不占位内容），首个可用图片就位前不会拉起画廊
• 图片加载失败的占位与重试不在本组件职责内（需要时在 urls 层先行校验或换用图片组件单独展示）