ImageGallery 图片预览

用法

基础

点击缩略图在全屏灯箱中打开；startIndex 指定当前预览的图片。

示例加载中...

追踪预览打开

<script setup lang="ts">
function onOpen({ index, item }: { index: number, item: { id: string } }) {
  analytics.track('gallery_open', { index, imageId: item.id })
}
</script>

<template>
  <TxImageGallery :items="images" @open="onOpen" @close="onClose" />
</template>

控制起始图片

startIndex 只选择预览索引，不会打开灯箱。

<template>
  <TxImageGallery :items="screenshots" :start-index="selectedIndex" />
</template>

最佳实践

使用稳定的 id，不要用数组索引作长期图库数据的 key。
信息性图片提供 name，按钮标签、alt 与预览标题才有意义。
列表规模保持适中：组件渲染全部缩略图，不做虚拟化。
不可信的远程图片 URL 先在应用边界归一化或代理。
不要在 @open 中同步改动 items，以免已打开的图片失效。

API 参考

属性

属性名	类型	默认值	说明
`items`	`ImageGalleryItem[]`	必填	缩略图及全屏预览的图片。
`startIndex`	`number`	`0`	当前预览索引，收敛到有效范围。
`previousLabel`	`string`	`'Previous image'`	上一张按钮的可访问名称。
`nextLabel`	`string`	`'Next image'`	下一张按钮的可访问名称。
`previousText`	`string`	`'Prev'`	上一张按钮的可见文字。
`nextText`	`string`	`'Next'`	下一张按钮的可见文字。
`previewTitle`	`string`	`'Preview'`	当前图片没有 `name` 时的预览标题。
`itemLabelFormatter`	`(index: number) => string`	(i) => `Image ${i + 1}`	图片没有 `name` 时生成显示名称。
`openLabelFormatter`	`(label: string) => string`	(label) => `Open ${label} preview`	由显示名称生成缩略图的 `aria-label`。

事件

事件名	参数	说明
`open`	`{ index: number, item: ImageGalleryItem }`	缩略图打开全屏预览后触发。
`close`	`void`	预览关闭时触发。

ImageGalleryItem

字段	类型	说明
`id`	`string`	缩略图的稳定 key。
`url`	`string`	缩略图与预览图的 URL。
`name`	`string`	可选显示名称，用于标签、alt 与预览标题。

概述

每个缩略图是原生 <button type="button">，aria-label 由 openLabelFormatter 生成。
缩略图与预览图的 alt 取 item.name；未命名图片有意使用空 alt。
灯箱困住 Tab 焦点，Escape 或关闭按钮关闭，焦点回到触发的缩略图。
导航有边界：首张禁用上一张，末张禁用下一张；按钮被禁用时焦点移到另一侧按钮。
图片在头栏与底栏之间等比完整显示，不裁切。
items 变为空时预览关闭、索引重置为 0。

技术实现

灯箱即 TxModal 的 fullscreen 模式（挂载到 body），不另写浮层。
源码：packages/tuffex/packages/components/src/image-gallery/。

查看源码

packages/tuffex/packages/components/src/image-gallery/index.ts