图片

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

基本用法

指示如何通过 fit 调整图像大小以适应其容器，与本机 object-fit 相同。

fill

contain

cover

none

scale-down

占位符

slot = placeholder 尚未加载图像时的自定义占位符内容

Default

Custom

加载失败

当 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 IconPicture from '~icons/ep/picture'

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>

延迟加载

TIP

从2.2.3开始支持原生loading，您可以使用loading = "lazy"替换lazy = true。

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

通过 lazy = true 使用延迟加载。设置后图像将加载，直到滚动到视图中。您可以通过 scroll-container 来指示添加滚动侦听器的滚动容器。如果未定义，将是最近的父容器，其溢出属性为auto或scroll。

图像预览

通过设置 previewSrcList 属性允许大图像预览。可以初始化initial-index预览的第一张图片的位置。默认初始位置为 0。

手动打开预览2.9.4

自定义工具栏 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-mobile'
import Back from '~icons/ep/back'
import DArrowRight from '~icons/ep/d-arrow-right'
import Download from '~icons/ep/download'
import Refresh from '~icons/ep/refresh'
import RefreshLeft from '~icons/ep/refresh-left'
import RefreshRight from '~icons/ep/refresh-right'
import Right from '~icons/ep/right'
import ZoomIn from '~icons/ep/zoom-in'
import ZoomOut from '~icons/ep/zoom-out'

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槽位就会显示进度内容。

图像API

图像属性

| 名称 | 描述 | 类型 | 默认 | | ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---- | --- | | 来源 | 图片来源，与原生相同。 | 字符串 | '' | | 适合 | 指示如何调整图像大小以适合其容器，与 object-fit 相同。 | 枚举 | '' | | 点击模式隐藏 | 启用预览时，使用此标志来控制点击背景是否可以退出预览模式。 | 布尔值 | 假 | | 加载 2.2.3 | 指示浏览器应如何加载图像，与native相同。 | 枚举 | — | | 懒惰 | 是否使用延迟加载。 | 布尔值 | 假 | | 滚动容器 | 使用延迟加载时添加滚动侦听器的容器。默认情况下，容器在使用延迟加载时添加滚动监听器。 | 字符串 / 对象 | — | | 替代 | 本机属性 alt。 | 字符串 | — | | 推荐人政策 | 本机属性 referrerPolicy。 | 字符串 | — | | 跨域 | 本机属性 crossorigin。 | 枚举 | — | | 预览-src-列表 | 允许大图像预览。 | 数组 | [] | | z 索引 | 设置图像预览 z-index。 | 数字 | — | | 初始索引 | 初始预览图像索引，小于url-list的长度。 | 数字 | 0 | | 关闭新闻转义 | 是否可以通过按 ESC 关闭图像查看器。 | 布尔值 | 真实 | | 预览-传送 | 是否将图像查看器附加到正文。嵌套父元素属性转换应将此属性设置为 true。 | 布尔值 | 假 | | 无限 | 查看器预览是否是无限的。 | 布尔值 | 真实 | | 缩放率 | 图像查看器缩放事件的缩放率。 | 数字 | 1.2 | 1.2 | | 规模 2.11.3 | 预览图像比例。 | 数字 | 1 | | 最小尺度 2.4.0 | 图像查看器缩放事件的最小比例。 | 数字 | 0.2 | 0.2 | | 最大规模 2.4.0 | 图像查看器缩放事件的最大比例。 | 数字 | 7 | | 显示进度 2.9.4 | 是否显示预览图像进度内容。 | 布尔值 | 假 |

图像事件

名称	描述	类型
负载	与本机负载相同。	`功能`
错误	与本机错误相同。	`功能`
开关	切换图像时触发。	`功能`
关闭	单击关闭按钮或 `hide-on-click-modal` 启用单击背景时触发。	`功能`
显示	当查看器显示	时触发`功能`

图像槽

名称	描述	类型
占位符	图像尚未加载时的自定义占位符内容。	-
错误	自定义图像加载失败的内容。	-
图像查看器插槽	当您允许大图像预览时，所有图像查看器插槽都可以使用。	-

图像曝光

名称	描述	类型
显示预览 2.9.4	手动打开预览大图	`功能`

图像查看器 API

图像查看器属性

| 名称 | 描述 | 类型 | 默认 | | ----------------- | --------------------------------------------------------------------- | ------------------- | ---- | --- | | url 列表 | 预览链接列表。 | 数组 | [] | | z 索引 | 预览背景 z-index。 | 数字 / 字符串 | — | | 初始索引 | 初始预览图像索引，小于或等于url-list的长度。 | 数字 | 0 | | 无限 | 预览是否无限。 | 布尔值 | 真实 | | 点击模式隐藏 | 用户点击背景时是否可以发出关闭事件。 | 布尔值 | 假 | | 传送 | 是否将图像本身附加到正文。嵌套父元素属性转换应将此属性设置为 true。 | 布尔值 | 假 | | 缩放率 2.2.27 | 图像查看器缩放事件的缩放率。 | 数字 | 1.2 | 1.2 | | 规模 2.11.3 | 预览图像比例。 | 数字 | 1 | | 最小尺度 2.4.0 | 图像查看器缩放事件的最小比例。 | 数字 | 0.2 | 0.2 | | 最大规模 2.4.0 | 图像查看器缩放事件的最大比例。 | 数字 | 7 | | 关闭新闻转义 | 是否可以通过按 ESC 关闭图像查看器。 | 布尔值 | 真实 | | 显示进度 2.9.4 | 是否显示预览图像进度内容 | 布尔值 | 假 |

图像查看器事件

名称	描述	类型
关闭	单击关闭按钮或 `hide-on-click-modal` 启用单击背景时触发。	`功能`
错误 2.11.3	与本机错误相同。	`功能`
开关	切换图像时触发。	`功能`
旋转 2.3.13	旋转图像时触发。	`功能`

图像查看器插槽

名称	描述	类型
观众	定制内容	-
进度 2.9.4	自定义进度内容（优先级高于`show-progress` prop）	`对象`
工具栏 2.9.4	自定义工具栏内容	`对象`
查看器错误 2.11.3	自定义图像加载失败的内容。	`对象`

图像查看器暴露

名称	描述	类型
设置活动项目	手动切换图像	`功能`

类型声明

显示声明

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

Empty 空状态

Infinite Scroll 无限滚动

图片 ​

基本用法 ​

占位符 ​

加载失败 ​

延迟加载 ​

图像预览 ​

手动打开预览2.9.4 ​

自定义工具栏 2.9.4 ​

自定义进度 2.9.4 ​

图像API ​

图像属性 ​

图像事件 ​

图像槽 ​

图像曝光 ​

图像查看器 API ​

图像查看器属性 ​

图像查看器事件 ​

图像查看器插槽 ​

图像查看器暴露 ​

类型声明 ​

图片