BizImageViewer 图片预览

图片缩略图列表 + 全屏预览：数据归一化（string[] 直传或对象数组字段映射）、缩略图与大图地址分离、limit 聚合占位、空态占位、缩略图覆盖层插槽，全屏预览基于 el-image-viewer（共享单实例 + 点击定位）。

相对参考实现的优化：零 any（归一化数据源完整 TS 类型）、url 列表 computed 缓存（替代模板内逐帧 map）、以渲染索引直接定位（替代 id 查找，O(1) 且无重复 id 风险）、布局改 flex gap、缩略图尺寸经 css 变量可覆盖、颜色统一走 EP 主题变量、空态双布尔互斥逻辑收敛为 show-empty + empty-text。

基础用法

images 传 url 字符串数组，点击缩略图打开全屏预览并定位到点击项；preview / switch / close 事件透传。

加载中...

点击任一缩略图打开全屏预览；预览内左右箭头 / 滚轮缩放 / Esc 关闭。图片每次刷新随机抽取。

最近事件：（未预览）｜（未切换）

全屏预览支持左右切换、滚轮缩放（zoom-rate 可调）、Esc 关闭。

<script setup lang="ts">
/** 基础用法：url 字符串数组直传，点击缩略图全屏预览（自动定位到点击项） */
import { ref } from 'vue'
import { BizImageViewer } from 'vue3-ep-biz-lib'

/** 在线图池：Unsplash 免费图库 CDN 直链，实测可直连加载 */
const PHOTO_POOL = [
  'photo-1506744038136-46273834b3fb',
  'photo-1469474968028-56623f02e42e',
  'photo-1470071459604-3b5ec3a7fe05',
  'photo-1501785888041-af3ef285b470',
  'photo-1441974231531-c6227db76b6e',
  'photo-1519681393784-d120267933ba',
]

/** 随机取 n 张不重复图片地址（每次刷新页面组合随机） */
const pickPhotoUrls = (n: number): string[] => {
  const pool = [...PHOTO_POOL]
  const picked: string[] = []
  while (picked.length < n && pool.length > 0) {
    const [id] = pool.splice(Math.floor(Math.random() * pool.length), 1)
    picked.push(`https://images.unsplash.com/${id}?w=800&h=600&fit=crop&q=70`)
  }
  return picked
}

const urls = pickPhotoUrls(3)

const lastPreview = ref('（未预览）')
const lastSwitch = ref('（未切换）')

const onPreview = (index: number): void => {
  lastPreview.value = `打开第 ${index + 1} 张`
}
const onSwitch = (index: number): void => {
  lastSwitch.value = `切换到第 ${index + 1} 张`
}
</script>

<template>
  <div>
    <BizImageViewer :images="urls" @preview="onPreview" @switch="onSwitch" @close="lastSwitch = '（已关闭）'" />
    <div class="tip">点击任一缩略图打开全屏预览；预览内左右箭头 / 滚轮缩放 / Esc 关闭。图片每次刷新随机抽取。</div>
    <div class="tip">最近事件：{{ lastPreview }}｜{{ lastSwitch }}</div>
  </div>
</template>

<style scoped>
.tip {
  margin-top: 8px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}
</style>

对象数据与字段映射

后端附件对象数组配合 src-key（缩略图）/ preview-src-key（预览大图）/ name-key（名称，渲染为 alt）；#item-extra 覆盖层展示名称与操作按钮，其点击不会误开预览。

加载中...

现场照片-01.jpg

加载中...

现场照片-02.jpg

加载中...

现场照片-03.jpg

item-extra 点击不会误开预览（删除按钮直接生效）；清空后展示空态占位。

组件库不内置接口与数据转换：业务侧准备数组后按字段名映射即可；清空数组查看空态。

<script setup lang="ts">
/** 对象数组 + 字段映射：src-key/preview-src-key/name-key，item-extra 覆盖层与空态切换 */
import { ref } from 'vue'
import { ElButton, ElMessage } from 'element-plus'
import { Delete } from '@element-plus/icons-vue'
import { BizImageViewer } from 'vue3-ep-biz-lib'

/** 模拟接口返回的附件结构（组件库不内置接口，数据由业务侧准备） */
type FileRecord = {
  id: number
  thumbPath: string
  filePath: string
  fileName: string
}

/** 在线图池：Unsplash 免费图库 CDN 直链，实测可直连加载 */
const PHOTO_POOL = [
  'photo-1506744038136-46273834b3fb',
  'photo-1469474968028-56623f02e42e',
  'photo-1470071459604-3b5ec3a7fe05',
  'photo-1501785888041-af3ef285b470',
  'photo-1441974231531-c6227db76b6e',
  'photo-1519681393784-d120267933ba',
]

/** 随机取 n 张不重复图片 id（每次刷新页面组合随机） */
const pickPhotoIds = (n: number): string[] => {
  const pool = [...PHOTO_POOL]
  const picked: string[] = []
  while (picked.length < n && pool.length > 0) {
    const [id] = pool.splice(Math.floor(Math.random() * pool.length), 1)
    picked.push(id)
  }
  return picked
}

/** 缩略图与原图同源不同尺寸：src-key 读小图，preview-src-key 读大图 */
const thumbUrl = (id: string): string => `https://images.unsplash.com/${id}?w=240&h=180&fit=crop&q=60`
const fullUrl = (id: string): string => `https://images.unsplash.com/${id}?w=1200&h=900&fit=crop&q=75`

/** 随机生成 n 条附件记录 */
const makeFiles = (n: number): FileRecord[] =>
  pickPhotoIds(n).map((id, i) => ({
    id: i + 1,
    thumbPath: thumbUrl(id),
    filePath: fullUrl(id),
    fileName: `现场照片-0${i + 1}.jpg`,
  }))

const files = ref<FileRecord[]>(makeFiles(3))

/** 插槽 index 即原始数据下标（rawIndex），直接按下标移除 */
const removeFile = (index: number): void => {
  const [removed] = files.value.splice(index, 1)
  ElMessage.success(`已移除「${removed?.fileName ?? ''}」`)
}
</script>

<template>
  <div>
    <BizImageViewer
      :images="files"
      src-key="thumbPath"
      preview-src-key="filePath"
      name-key="fileName"
    >
      <template #item-extra="{ item, index }">
        <div class="name-bar">{{ item.name }}</div>
        <ElButton
          class="del-btn"
          type="danger"
          :icon="Delete"
          circle
          size="small"
          @click.stop="removeFile(index)"
        />
      </template>
    </BizImageViewer>

    <div class="actions">
      <ElButton size="small" @click="files = []">清空（看空态）</ElButton>
      <ElButton size="small" @click="files = makeFiles(2)">恢复数据（重新随机）</ElButton>
    </div>
    <div class="tip">item-extra 点击不会误开预览（删除按钮直接生效）；清空后展示空态占位。</div>
  </div>
</template>

<style scoped>
.actions {
  display: flex;
  gap: 8px;
  margin-top: 12px;
}

.tip {
  margin-top: 8px;
  font-size: 13px;
  color: var(--el-text-color-secondary);
}

.name-bar {
  padding: 2px 6px;
  border-radius: 0 0 var(--el-border-radius-base) var(--el-border-radius-base);
  background: var(--el-mask-color);
  backdrop-filter: blur(2px);
  color: #fff;
  font-size: 12px;
  text-align: center;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

.del-btn {
  position: absolute;
  top: 4px;
  right: 4px;
}
</style>

其他用法

limit 聚合占位（+N 点击定位到首张隐藏图）、无效地址的加载失败态、preview=false 纯缩略图模式（配合 click-thumb 自定义行为）、css 变量覆盖尺寸、实例方法 open() 编程式打开。

limit 聚合（limit=4，共 9 张）

加载中...

加载失败态（首项为无效地址）

加载中...

纯缩略图模式（preview=false + click-thumb 自定义行为）

加载中...

尺寸定制（css 变量覆盖为 72×54）

加载中...

实例方法 open() 编程式打开

加载中...

尺寸规格默认 120×90，通过 --biz-image-viewer-thumb-width/height 覆盖。

<script setup lang="ts">
/** 扩展能力：limit 聚合 / 纯缩略图模式 / 加载失败态 / 尺寸变量覆盖 / 实例方法 */
import { ref } from 'vue'
import { ElButton, ElMessage } from 'element-plus'
import { BizImageViewer } from 'vue3-ep-biz-lib'
import type { BizImageViewerInstance } from 'vue3-ep-biz-lib'

/** 在线图池：Unsplash 免费图库 CDN 直链，实测可直连加载 */
const PHOTO_POOL = [
  'photo-1506744038136-46273834b3fb',
  'photo-1469474968028-56623f02e42e',
  'photo-1470071459604-3b5ec3a7fe05',
  'photo-1501785888041-af3ef285b470',
  'photo-1441974231531-c6227db76b6e',
  'photo-1519681393784-d120267933ba',
  'photo-1472214103451-9374bd1c798e',
  'photo-1501594907352-04cda38ebc29',
  'photo-1447752875215-b2761acb3c5d',
  'photo-1433086966358-54859d0ed716',
  'photo-1507525428034-b723cf961d3e',
  'photo-1500530855697-b586d89ba3ee',
]

/** 随机取 n 张不重复图片地址（每次刷新页面组合随机） */
const pickPhotoUrls = (n: number): string[] => {
  const pool = [...PHOTO_POOL]
  const picked: string[] = []
  while (picked.length < n && pool.length > 0) {
    const [id] = pool.splice(Math.floor(Math.random() * pool.length), 1)
    picked.push(`https://images.unsplash.com/${id}?w=800&h=600&fit=crop&q=70`)
  }
  return picked
}

/** limit=4：仅展示前 4 张，其余聚合为 +5 占位（点击定位到第 5 张） */
const many = pickPhotoUrls(9)

/** 首项为空地址：演示 #error 插槽加载失败态（真实数据应全部可加载） */
const broken = ['', many[0] ?? '']
const noPreviewList = pickPhotoUrls(2)

const onThumbWithoutPreview = (index: number): void => {
  ElMessage.info(`自定义点击行为：第 ${index + 1} 张（未开预览）`)
}

/** 实例方法：open() 编程式打开 */
const viewerRef = ref<BizImageViewerInstance | null>(null)
</script>

<template>
  <div>
    <h4>limit 聚合（limit=4，共 9 张）</h4>
    <BizImageViewer :images="many" :limit="4" hide-on-click-modal />

    <h4>加载失败态（首项为无效地址）</h4>
    <BizImageViewer :images="broken" />

    <h4>纯缩略图模式（preview=false + click-thumb 自定义行为）</h4>
    <BizImageViewer :images="noPreviewList" :preview="false" @click-thumb="onThumbWithoutPreview" />

    <h4>尺寸定制（css 变量覆盖为 72×54）</h4>
    <BizImageViewer
      :images="many.slice(0, 3)"
      style="--biz-image-viewer-thumb-width: 72px; --biz-image-viewer-thumb-height: 54px"
    />

    <h4>实例方法 open() 编程式打开</h4>
    <ElButton size="small" @click="viewerRef?.open(2)">打开第 3 张</ElButton>
    <BizImageViewer ref="viewerRef" :images="many" style="margin-top: 8px" />
  </div>
</template>

<style scoped>
h4 {
  margin: 16px 0 8px;
  font-size: 14px;
  font-weight: 600;
  color: var(--el-text-color-primary);
}

h4:first-child {
  margin-top: 0;
}
</style>

商品相册编辑

加载中...

共 6 张；limit=4 时超出聚合为 +2（点击进入预览定位首张隐藏图）；右上角删除由 item-extra 插槽渲染。

相册编辑场景：对象数组 + 字段映射（src-key 缩略图 / preview-src-key 原图分离）、limit=4 聚合 +N、item-extra 覆盖层渲染删除按钮（点击不误触全屏预览）。

<script setup lang="ts">
/** 场景：商品相册编辑——item-extra 覆盖删除、limit +N 聚合、对象数组字段映射 */
import { ref } from 'vue'
import { ElButton, ElIcon, ElMessage } from 'element-plus'
import { Delete } from '@element-plus/icons-vue'
import { BizImageViewer } from 'vue3-ep-biz-lib'

interface AlbumPhoto {
  id: number
  thumb: string
  raw: string
  name: string
}

const photos = ref<AlbumPhoto[]>(
  Array.from({ length: 6 }, (_unused, i) => ({
    id: i + 1,
    thumb: `https://images.unsplash.com/photo-1550005809-91ad75fb315f?w=160&h=120&fit=crop&sig=${i}`,
    raw: `https://images.unsplash.com/photo-1550005809-91ad75fb315f?w=1200&h=900&fit=crop&sig=${i}`,
    name: `商品图 ${i + 1}`,
  }))
)

const onRemove = (index: number): void => {
  const target = photos.value[index]
  if (target === undefined) return
  photos.value = photos.value.filter((photo) => photo.id !== target.id)
  ElMessage.success(`已移除「${target.name}」`)
}
</script>

<template>
  <div style="max-width: 560px">
    <BizImageViewer
      :images="photos"
      src-key="thumb"
      preview-src-key="raw"
      name-key="name"
      :limit="4"
      lazy
      style="--biz-image-viewer-thumb-width: 88px; --biz-image-viewer-thumb-height: 66px"
    >
      <!-- item-extra 覆盖层：点击不误触全屏预览（组件已做隔离） -->
      <template #item-extra="{ index }">
        <ElButton circle size="small" type="danger" @click="onRemove(index)">
          <ElIcon><Delete /></ElIcon>
        </ElButton>
      </template>
    </BizImageViewer>
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      共 {{ photos.length }} 张；limit=4 时超出聚合为 +{{ Math.max(photos.length - 4, 0) }}（点击进入预览定位首张隐藏图）；右上角删除由 item-extra 插槽渲染。
    </div>
  </div>
</template>

故障举证照片

加载中...

故障点全景 · 09:12

加载中...

铭牌特写 · 09:15

加载中...

更换备件后 · 10:02

工单号 WO-20260923-0088 现场举证照片；点击缩略图全屏查看原图

工单场景：item-extra 覆盖层展示「照片名 + 拍摄时间」徽标，点击缩略图全屏核验。

<script setup lang="ts">
/** 场景：故障举证——item-extra 展示照片名与拍摄时间徽标 */
import { BizImageViewer } from 'vue3-ep-biz-lib'

const photos = [
  { url: 'https://images.unsplash.com/photo-1581091226825-a6a2a5aee158?w=200&h=140&fit=crop', name: '故障点全景', time: '09:12' },
  { url: 'https://images.unsplash.com/photo-1581092160562-40aa08e78837?w=200&h=140&fit=crop', name: '铭牌特写', time: '09:15' },
  { url: 'https://images.unsplash.com/photo-1565043666747-69f6646db940?w=200&h=140&fit=crop', name: '更换备件后', time: '10:02' },
]
</script>

<template>
  <div style="max-width: 560px">
    <BizImageViewer :images="photos" src-key="url" name-key="name">
      <template #item-extra="{ index }">
        <span style="padding: 0 6px; font-size: 12px; color: #fff; background: rgba(0, 0, 0, 0.55); border-radius: 3px">
          {{ photos[index]?.name }} · {{ photos[index]?.time }}
        </span>
      </template>
    </BizImageViewer>
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      工单号 WO-20260923-0088 现场举证照片；点击缩略图全屏查看原图
    </div>
  </div>
</template>

证件双面核验

正面（人像面）

反面（国徽面）

加载中...

KYC 场景：正反面两张 + 懒加载，点击大图人工核验；css 变量放大缩略图。

<script setup lang="ts">
/** 场景：证件双面核验——正反面两张、懒加载、点击大图人工核验 */
import { BizImageViewer } from 'vue3-ep-biz-lib'

const sides = [
  { side: '正面（人像面）', url: 'https://images.unsplash.com/photo-1554224154-26032ffc0d07?w=240&h=160&fit=crop' },
  { side: '反面（国徽面）', url: 'https://images.unsplash.com/photo-1554224155-1696413565d3?w=240&h=160&fit=crop' },
]
</script>

<template>
  <div style="max-width: 420px">
    <div v-for="side in sides" :key="side.side" style="margin-bottom: 6px; font-size: 13px; color: var(--el-text-color-secondary)">{{ side.side }}</div>
    <BizImageViewer :images="sides" src-key="url" name-key="side" lazy style="--biz-image-viewer-thumb-width: 180px; --biz-image-viewer-thumb-height: 120px" />
  </div>
</template>

会话图片附件

加载中...

本组共 8 张，limit=5 时展示前 5 张 + 「+3」聚合块；点击 +3 打开预览并定位到第 6 张

IM 场景：8 张图 limit=5 聚合「+3」，点击聚合块打开预览并定位到第 6 张。

<script setup lang="ts">
/** 场景：会话图片附件——数量多时 limit 聚合 +N，点击定位首张隐藏图 */
import { BizImageViewer } from 'vue3-ep-biz-lib'

const pool = [
  'photo-1506744038136-46273834b3fb',
  'photo-1469474968028-56623f02e42e',
  'photo-1470071459604-3b5ec3a7fe05',
  'photo-1501785888041-af3ef285b470',
  'photo-1441974231531-c6227db76b6e',
  'photo-1519681393784-d120267933ba',
  'photo-1472214103451-9374bd1c798e',
  'photo-1493246507139-91e8fad9978e',
]

const urls = pool.map((id) => `https://images.unsplash.com/${id}?w=160&h=120&fit=crop&q=60`)
</script>

<template>
  <div style="max-width: 520px">
    <BizImageViewer :images="urls" :limit="5" lazy />
    <div style="margin-top: 8px; font-size: 13px; color: var(--el-text-color-secondary)">
      本组共 {{ urls.length }} 张，limit=5 时展示前 5 张 + 「+3」聚合块；点击 +3 打开预览并定位到第 6 张
    </div>
  </div>
</template>

Props

属性名	类型	默认值	说明
images	`string[] \| BizImageViewerItem[]`	`[]`	图片数据：url 数组直传，或对象数组配合字段映射
src-key	`string`	`''`	对象数组时缩略图地址字段名（`''` 直接读 `item.src`）
preview-src-key	`string`	`''`	预览大图地址字段名（`''` 与缩略图同源）
name-key	`string`	`''`	名称字段名（渲染为缩略图 alt）
preview	`boolean`	`true`	点击缩略图是否打开全屏预览
limit	`number`	`0`	最多展示缩略图数量，`0` 全部；超出聚合为 `+N` 占位
lazy	`boolean`	`false`	缩略图懒加载（滚动进入视口才加载）
show-empty	`boolean`	`true`	空数据是否展示占位
empty-text	`string`	`'暂无图片'`	空数据占位文案
hide-on-click-modal	`boolean`	`false`	全屏预览：点击遮罩关闭
close-on-press-escape	`boolean`	`true`	全屏预览：Esc 关闭
zoom-rate	`number`	`1.2`	全屏预览：滚轮缩放速率
teleported	`boolean`	`true`	全屏预览：是否挂载到 body

BizImageViewerItem：{ src: string; previewSrc?: string; name?: string }。根节点透传 $attrs（class/style 等）。

Events

事件名	参数	说明
click-thumb	`(index: number, item: BizImageViewerDataItem)`	点击缩略图（`preview=false` 时作为自定义行为入口；item 为数据源原始项）
preview	`(index: number)`	全屏预览打开
close	—	全屏预览关闭
switch	`(index: number)`	全屏预览切换图片（EP 原生透传）

Slots

插槽名	说明
placeholder	缩略图加载中占位（作用于每张缩略图）
error	缩略图加载失败占位（作用于每张缩略图）
empty	空数据占位（默认 el-empty）
item-extra	缩略图覆盖层，作用域 `{ item: 归一化项, index: number }`；点击不会误开预览

Expose

属性/方法	说明
open	`(index = 0) => void` 编程式打开全屏预览
close	`() => void` 编程式关闭全屏预览
hasExtra	`ComputedRef<boolean>` 是否启用 item-extra 覆盖层

BizImageViewer 图片预览 ​

基础用法 ​

对象数据与字段映射 ​

其他用法 ​

limit 聚合（limit=4，共 9 张）

加载失败态（首项为无效地址）

纯缩略图模式（preview=false + click-thumb 自定义行为）

尺寸定制（css 变量覆盖为 72×54）

实例方法 open() 编程式打开

商品相册编辑 ​

故障举证照片 ​

证件双面核验 ​

会话图片附件 ​

Props ​

Events ​

Slots ​

Expose ​

BizImageViewer 图片预览

基础用法

对象数据与字段映射

其他用法

商品相册编辑

故障举证照片

证件双面核验

会话图片附件

Props

Events

Slots

Expose