Image 图片

Image 用于展示图片内容，在保留原生 img 特性的基础上，支持懒加载、自定义占位、加载失败回退和大图预览。VISTA B 直接使用 Element Plus 的 el-image 与 el-image-viewer。

基础用法

通过 fit 设置图片如何适应容器，取值与原生 CSS object-fit 一致。

fill

contain

cover

none

scale-down

vue

<el-image
  style="width: 100px; height: 100px"
  :src="url"
  fit="cover"
/>

占位内容

通过 placeholder 插槽可以自定义图片加载中的占位内容。

Default

Custom

vue

<el-image :src="src">
  <template #placeholder>
    <div class="image-slot">Loading...</div>
  </template>
</el-image>

加载失败

通过 error 插槽自定义缩略图加载失败时的内容；通过 viewer-error 插槽自定义预览大图加载失败时的内容。

vue

<el-image src="https://empty">
  <template #error>
    <div class="image-slot">
      <el-icon><IconPicture /></el-icon>
    </div>
  </template>
</el-image>

懒加载

设置 lazy 后，图片滚动到可视范围内才会加载。也可以使用浏览器原生 loading="lazy" 作为加载策略。

vue

<el-image v-for="url in urls" :key="url" :src="url" lazy />
<el-image :src="url" loading="lazy" />

图片预览

通过 preview-src-list 开启大图预览。initial-index 用于设置预览时默认打开的图片索引。

未操作

vue

<el-image
  :src="url"
  :preview-src-list="srcList"
  :initial-index="4"
  show-progress
  fit="cover"
/>

手动打开预览

组件暴露 showPreview 方法，可通过按钮手动打开预览；也可以直接使用 el-image-viewer 进行受控展示。

vue

<script setup>
import { ref } from 'vue'

const imageRef = ref()

const openPreview = () => {
  imageRef.value?.showPreview()
}
</script>

<template>
  <el-button @click="openPreview">open preview</el-button>
  <el-image ref="imageRef" :src="url" :preview-src-list="srcList" />
</template>

自定义工具栏

通过 toolbar 插槽可以自定义预览工具栏内容。插槽提供 actions、prev、next、reset、activeIndex 和 setActiveItem。

vue

<el-image :src="url" :preview-src-list="srcList">
  <template #toolbar="{ actions, prev, next, reset }">
    <el-icon @click="prev"><Back /></el-icon>
    <el-icon @click="next"><Right /></el-icon>
    <el-icon @click="actions('zoomIn')"><ZoomIn /></el-icon>
    <el-icon @click="reset"><Refresh /></el-icon>
  </template>
</el-image>

自定义进度条

通过 progress 插槽可以自定义预览时的进度内容。使用该插槽时，内容优先级高于 show-progress。

vue

<el-image :src="url" :preview-src-list="srcList">
  <template #progress="{ activeIndex, total }">
    <span>{{ activeIndex + 1 }} / {{ total }}</span>
  </template>
</el-image>

API

Image 属性

属性	说明	类型	默认值
`src`	图片源地址，同原生属性一致	`string`	`''`
`fit`	图片如何适应容器	`fill` / `contain` / `cover` / `none` / `scale-down` / `''`	`''`
`hide-on-click-modal`	开启预览时，是否可以点击遮罩层关闭预览	`boolean`	`false`
`loading`	浏览器加载图像的策略	`eager` / `lazy`	空
`lazy`	是否使用懒加载	`boolean`	`false`
`scroll-container`	懒加载监听滚动事件的容器	`string` / `HTMLElement`	空
`alt`	原生 `alt` 属性	`string`	空
`referrerpolicy`	原生 `referrerpolicy` 属性	`string`	空
`crossorigin`	原生 `crossorigin` 属性	`anonymous` / `use-credentials` / `''`	空
`preview-src-list`	开启图片预览功能	`string[]`	`[]`
`z-index`	设置图片预览的 `z-index`	`number`	空
`initial-index`	初始预览图片索引，小于 `preview-src-list` 的长度	`number`	`0`
`close-on-press-escape`	是否可以通过 ESC 关闭 Image Viewer	`boolean`	`true`
`preview-teleported`	Image Viewer 是否插入至 `body`	`boolean`	`false`
`infinite`	是否可以无限循环预览	`boolean`	`true`
`zoom-rate`	图片预览缩放速率	`number`	`1.2`
`scale`	预览图片缩放比例	`number`	`1`
`min-scale`	图片预览最小缩放比例	`number`	`0.2`
`max-scale`	图片预览最大缩放比例	`number`	`7`
`show-progress`	是否在预览图片时显示进度	`boolean`	`false`

Image 事件

事件名	说明	类型
`load`	图片加载成功时触发	`(event: Event) => void`
`error`	图片加载失败时触发	`(event: Event) => void`
`switch`	切换预览图片时触发	`(index: number) => void`
`close`	关闭预览时触发	`() => void`
`show`	Viewer 显示时触发	`() => void`

Image 插槽

插槽	说明
`placeholder`	图片尚未加载时的自定义占位内容
`error`	图片加载失败时的自定义内容
`viewer`	大图预览中的自定义内容
`progress`	大图预览中的自定义进度内容
`toolbar`	大图预览中的自定义工具栏内容
`viewer-error`	大图预览加载失败时的自定义内容

Image 方法

方法名	说明	类型
`showPreview`	手动打开大图预览	`() => void`

Image Viewer 属性

属性	说明	类型	默认值
`url-list`	用于预览的图片链接列表	`string[]`	`[]`
`z-index`	预览遮罩层的 `z-index`	`number` / `string`	空
`initial-index`	初始预览图片索引，小于 `url-list` 的长度	`number`	`0`
`infinite`	是否可以无限循环预览	`boolean`	`true`
`hide-on-click-modal`	是否可以点击遮罩层关闭预览	`boolean`	`false`
`teleported`	Image Viewer 是否插入至 `body`	`boolean`	`false`
`zoom-rate`	图片预览缩放速率	`number`	`1.2`
`scale`	预览图片缩放比例	`number`	`1`
`min-scale`	图片预览最小缩放比例	`number`	`0.2`
`max-scale`	图片预览最大缩放比例	`number`	`7`
`close-on-press-escape`	是否可以通过 ESC 关闭 Image Viewer	`boolean`	`true`
`show-progress`	是否显示预览图片的进度内容	`boolean`	`false`

Image Viewer 事件

事件名	说明	类型
`close`	关闭预览时触发	`() => void`
`error`	图片加载失败时触发	`(event: Event) => void`
`switch`	切换预览图片时触发	`(index: number) => void`
`rotate`	旋转图片时触发	`(deg: number) => void`

Image Viewer 插槽

插槽	说明
`default`	自定义预览内容
`progress`	自定义进度内容
`toolbar`	自定义工具栏内容
`viewer-error`	自定义图片加载失败内容

Image Viewer 方法

方法名	说明	类型
`setActiveItem`	手动切换图片	`(index: number) => void`

使用提醒

业务图片建议始终补充 alt，重要图片需要设置加载失败兜底内容。大图预览适合查看同一组图片，预览列表应保持同类内容，避免把不同业务含义的图片混在一个 Viewer 中。

Image 图片 ​

基础用法 ​

占位内容 ​

加载失败 ​

懒加载 ​

图片预览 ​

手动打开预览 ​

自定义工具栏 ​

自定义进度条 ​

API ​

Image 属性 ​

Image 事件 ​

Image 插槽 ​

Image 方法 ​

Image Viewer 属性 ​

Image Viewer 事件 ​

Image Viewer 插槽 ​

Image Viewer 方法 ​

使用提醒 ​