Image 图片

除了 img 的原生特性外，还支持懒加载，自定义占位符、加载失败提示等。

基础用法

通过 fit 确定图片如何适应到容器框，同原生 object-fit。

填充色

contain (保持比例)

cover (覆盖)

none (无)

scale-down (缩小)

占位内容

可通过 slot = placeholder 自定义图片未加载时的占位内容

默认值

自定义

加载中...

加载失败

可通过 slot = error 和 slot = viewer-error 自定义加载失败内容。

vue

<template>
  <div class="demo-image__error" flex gap-2>
    <el-image />
    <el-image>
      <template #error>
        <div class="image-viewer-slot image-slot">
          <el-icon><icon-picture /></el-icon>
        </div>
      </template>
    </el-image>
    <el-image :src="url" :preview-src-list="srcList" show-progress>
      <template #viewer-error="{ activeIndex, src }">
        <div class="image-slot viewer-error">
          <el-icon><icon-picture /></el-icon>
          <span>
            this is viewer-error slot. current index: {{ activeIndex }}. src:
            {{ src }}
          </span>
        </div>
      </template>
    </el-image>
    <el-button @click="showPreview = true"> preview controlled </el-button>

    <el-image-viewer
      v-if="showPreview"
      show-progress
      :url-list="srcList"
      @close="showPreview = false"
    >
      <template #viewer-error="{ activeIndex, src }">
        <div class="image-slot viewer-error">
          <el-icon><icon-picture /></el-icon>
          <span>
            this is viewer-error slot. current index: {{ activeIndex }}. src:
            {{ src }}
          </span>
        </div>
      </template>
    </el-image-viewer>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Picture as IconPicture } from '@element-plus/icons-vue'

const showPreview = ref(false)

const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://errorSrc',
]
const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
</script>

<style scoped>
.demo-image__error .el-image {
  max-width: 300px;
  max-height: 200px;
  width: 100%;
}

.demo-image__error .image-slot {
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
  font-size: 30px;
  height: 200px;
  background: #fff;
}
.demo-image__error .image-slot .el-icon {
  font-size: 30px;
}
.image-viewer-slot {
  background: var(--el-fill-color-light);
}
.viewer-error {
  color: #000;
}
</style>

懒加载

提示

2.2.3 版本起支持原生 loading 属性，你可以使用 loading = "lazy" 代替 lazy = true。

如果当前浏览器支持原生懒加载，则优先使用原生懒加载，否则通过滚动实现。

可通过 lazy = true 开启懒加载。开启后，图片会在滚动到可视区域时才加载。可以通过 scroll-container 指定监听滚动的容器。如果不指定，则为最近一个 overflow 值为 auto 或 scroll 的父容器。

图片预览

可通过 previewSrcList 开启预览大图的功能。可以通过 initial-index 初始化第一张预览图片的索引。默认初始索引为 0。

手动开启预览 2.9.4

可通过 toolbar 插槽自定义工具栏内容，从 2.9.7 版本开始，该插槽新增了 setActiveItem 函数，可以根据索引进行切换。

vue

<template>
  <div class="demo-image__custom-toolbar">
    <el-image
      style="width: 100px; height: 100px"
      :src="url"
      :preview-src-list="srcList"
      fit="cover"
      show-progress
    >
      <template
        #toolbar="{ actions, prev, next, reset, activeIndex, setActiveItem }"
      >
        <el-icon @click="prev"><Back /></el-icon>
        <el-icon @click="next"><Right /></el-icon>
        <el-icon @click="setActiveItem(srcList.length - 1)">
          <DArrowRight />
        </el-icon>
        <el-icon @click="actions('zoomOut')"><ZoomOut /></el-icon>
        <el-icon
          @click="actions('zoomIn', { enableTransition: false, zoomRate: 2 })"
        >
          <ZoomIn />
        </el-icon>
        <el-icon
          @click="
            actions('clockwise', { rotateDeg: 180, enableTransition: false })
          "
        >
          <RefreshRight />
        </el-icon>
        <el-icon @click="actions('anticlockwise')"><RefreshLeft /></el-icon>
        <el-icon @click="reset"><Refresh /></el-icon>
        <el-icon @click="download(activeIndex)"><Download /></el-icon>
      </template>
    </el-image>
  </div>
</template>

<script lang="ts" setup>
import { ElIcon } from 'element-plus'
import {
  Back,
  DArrowRight,
  Download,
  Refresh,
  RefreshLeft,
  RefreshRight,
  Right,
  ZoomIn,
  ZoomOut,
} from '@element-plus/icons-vue'

const url =
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg'
const srcList = [
  'https://fuss10.elemecdn.com/a/3f/3302e58f9a181d2509f3dc0fa68b0jpeg.jpeg',
  'https://fuss10.elemecdn.com/1/34/19aa98b1fcb2781c4fba33d850549jpeg.jpeg',
  'https://fuss10.elemecdn.com/0/6f/e35ff375812e6b0020b6b4e8f9583jpeg.jpeg',
  'https://fuss10.elemecdn.com/9/bb/e27858e973f5d7d3904835f46abbdjpeg.jpeg',
  'https://fuss10.elemecdn.com/d/e6/c4d93a3805b3ce3f323f7974e6f78jpeg.jpeg',
  'https://fuss10.elemecdn.com/3/28/bbf893f792f03a54408b3b7a7ebf0jpeg.jpeg',
  'https://fuss10.elemecdn.com/2/11/6535bcfb26e4c79b48ddde44f4b6fjpeg.jpeg',
]

const download = (index: number) => {
  const url = srcList[index]
  const suffix = url.slice(url.lastIndexOf('.'))
  const filename = Date.now() + suffix

  fetch(url)
    .then((response) => response.blob())
    .then((blob) => {
      const blobUrl = URL.createObjectURL(new Blob([blob]))
      const link = document.createElement('a')
      link.href = blobUrl
      link.download = filename
      document.body.appendChild(link)
      link.click()
      URL.revokeObjectURL(blobUrl)
      link.remove()
    })
}
</script>

自定义进度 2.9.4

通过设置 show-progress 属性来控制预览图片时是否显示进度。在 2.9.8 版本后，只要使用了 progress 插槽，就会显示进度内容。

Image API

Image 属性

名称	描述	类型	默认值
src	图片源，同原生。	`string`	''
fit	确定图片如何适应到容器框，同 object-fit。	`枚举`	''
hide-on-click-modal	开启预览时，是否可以通过点击遮罩层关闭预览。	`boolean`	false
loading 2.2.3	告知浏览器如何加载图片，同原生。	`枚举`	—
lazy	是否开启懒加载。	`boolean`	false
scroll-container	开启懒加载后，监听滚动的容器。	`string` / `object`	—
alt	原生 `alt` 属性。	`string`	—
referrerpolicy	原生 referrerPolicy 属性。	`string`	—
crossorigin	原生 crossorigin 属性。	`枚举`	—
preview-src-list	开启预览大图功能。	`array`	[]
z-index	设置图片预览的 z-index。	`number`	—
initial-index	初始预览图像索引，小于 `url-list` 的长度。	`number`	0
close-on-press-escape	是否可以通过按下 ESC 关闭图片预览。	`boolean`	true
preview-teleported	是否将查看器插入 body。如果父元素有 transform 属性，则需要将该属性设置为 `true`。	`boolean`	false
infinite	是否可以循环预览。	`boolean`	true
zoom-rate	图片查看器缩放事件的缩放比例。	`number`	1.2
scale 2.11.3	预览图片的缩放比例。	`number`	1
min-scale 2.4.0	图片查看器缩放事件的最小缩放比例。	`number`	0.2
max-scale 2.4.0	图片查看器缩放事件的最大缩放比例。	`number`	7
show-progress 2.9.4	是否显示预览图片的进度内容。	`boolean`	false

Image 事件

名称	描述	类型
load	原生 load 事件。	`Function`
error	原生 error 事件。	`Function`
switch	切换图像时触发。	`Function`
关闭	点击关闭按钮或在开启 `hide-on-click-modal` 时点击遮罩层触发。	`Function`
show	查看器显示时触发	`Function`

Image 插槽

名称	描述	类型
占位符	图片未加载时的占位内容。	-
error	图片加载失败的内容。	-
图片查看器插槽	当您开启预览大图功能时，可以使用所有图片查看器插槽。	-

Image 暴露的方法

名称	描述	类型
showPreview 2.9.4	手动打开大图预览	`Function`

Image Viewer API

Image Viewer 属性

名称	描述	类型	默认值
url-list	预览链接列表。	`array`	[]
z-index	预览遮罩层的 z-index。	`number` / `string`	—
initial-index	初始预览图像索引，小于或等于 `url-list` 的长度。	`number`	0
infinite	是否可以循环预览。	`boolean`	true
hide-on-click-modal	点击遮罩层是否可以触发关闭事件。	`boolean`	false
teleported	是否将图片本身插入 body。如果父元素有 transform 属性，则需要将该属性设置为 `true`。	`boolean`	false
zoom-rate 2.2.27	图片查看器缩放事件的缩放比例。	`number`	1.2
scale 2.11.3	预览图片的缩放比例。	`number`	1
min-scale 2.4.0	图片查看器缩放事件的最小缩放比例。	`number`	0.2
max-scale 2.4.0	图片查看器缩放事件的最大缩放比例。	`number`	7
close-on-press-escape	是否可以通过按下 ESC 关闭图片预览。	`boolean`	true
show-progress 2.9.4	是否显示预览图片的进度内容	`boolean`	false

Image Viewer 事件

名称	描述	类型
关闭	点击关闭按钮或在开启 `hide-on-click-modal` 时点击遮罩层触发。	`Function`
error 2.11.3	原生 error 事件。	`Function`
switch	切换图像时触发。	`Function`
rotate 2.3.13	旋转图像时触发。	`Function`

Image Viewer 插槽

名称	描述	类型
viewer	自定义内容	-
progress 2.9.4	自定义进度内容（优先级高于 `show-progress` 属性）	`object`
toolbar 2.9.4	自定义工具栏内容	`object`
viewer-error 2.11.3	图片加载失败的内容。	`object`

Image Viewer 暴露的方法

名称	描述	类型
setActiveItem	手动切换图片	`Function`

类型声明

显示声明

type ImageViewerAction = 'zoomIn' | 'zoomOut' | 'clockwise' | 'anticlockwise'
type ImageViewerActionOptions = {
  enableTransition?: boolean
  zoomRate?: number
  rotateDeg?: number
}