Skip to content

ImagePreview 图片预览

多图预览组件,作为独立顶层组件存在(不挂在 Image 命名空间下)。

何时使用

  • 多张图片需要统一预览,支持上一张 / 下一张切换。
  • 缩略图列表 + 大图预览的画廊场景。
  • 需要受控预览状态(外部按钮触发打开第 N 张)。

items 模式

最简用法:把图片数组传给 items,组件自动渲染缩略图列表,点击打开预览。

items 也接 string[] 简写:

受控预览

preview 对象进入受控模式。外部按钮控制打开 / 关闭 / 当前下标。

缩放 + 键盘导航

打开预览后:

  • + / / 按钮缩放(默认上限 6×,下限 0.25×)。
  • ArrowLeft / ArrowRight 切换上 / 下一张(循环)。
  • Escape 关闭预览。

默认 slot 模式

不传 items 时,缩略图完全由父组件渲染;预览状态走受控,由父组件决定当前显示哪张。

ImagePreview 参数

参数类型默认说明
itemsstring[]{ src: string; alt?: string }[]--
preview--受控预览状态;传则受控,未传则内部维护
maxZoomnumber6缩放上限
minZoomnumber0.25缩放下限

ImagePreview 事件

事件名参数说明
update:preview受控模式回写
changecurrent: number当前显示图片下标变化
visible-changevisible: boolean打开 / 关闭预览

ImagePreview 插槽

插槽名说明
default仅未传 items 时生效;缩略图等内容由父组件自定义渲染

行为说明

  • 循环切换prev 在首张回到末尾;next 在末尾回到首张。
  • 键盘监听:仅在 visible=true 时绑定 window.keydown,关闭后解绑;组件卸载强制解绑防泄漏。
  • 缩放重置:每次切换图片自动 scale=1
  • z-index 1100:高于 Modal / Drawer,避免被覆盖。

Released under the MIT License.