Image 图片

在原生 img 能力基础上，支持懒加载、自定义占位与加载失败展示等。

基础用法

通过 fit 指定图片如何适应容器，行为同原生 object-fit。

fill

contain

cover

none

scale-down

占位内容

未加载完成前可通过 placeholder 插槽自定义占位。

Default

Custom

加载失败

加载出错时可通过 error 与 viewer-error 插槽自定义展示。

vue

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

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

<script setup lang="ts">
import { ref } from 'vue'
import { Picture as IconPicture } from '@uniboot/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 .u-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 .u-icon {
  font-size: 30px;
}
.image-viewer-slot {
  background: var(--u-fill-color-light);
}
.viewer-error {
  color: #000;
}
</style>

懒加载

TIP

支持原生 loading 属性，可用 loading="lazy" 替代 lazy = true。

若浏览器支持原生懒加载则优先使用，否则由组件基于滚动实现。

lazy 为 true 时进入可视区域再加载。scroll-container 指定监听滚动的容器；未设置时取最近的 overflow 为 auto 或 scroll 的父级。

图片预览

设置 previewSrcList 开启大图预览；initial-index 指定首张预览索引，默认 0。

手动打开预览

自定义工具栏

使用 toolbar 插槽自定义工具栏；插槽提供 setActiveItem，可按索引切换图片。

vue

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

<script lang="ts" setup>
import { UIcon } from 'uniboot-ui'
import {
  Back,
  DArrowRight,
  Download,
  Refresh,
  RefreshLeft,
  RefreshRight,
  Right,
  ZoomIn,
  ZoomOut,
} from '@uniboot/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>

自定义进度

show-progress 控制是否显示预览进度；只要使用 progress 插槽即会展示进度内容。

图片 API

图片属性

名称	说明	类型	默认值
src	图片地址，同原生	`string`	''
fit	适应容器的方式，同 object-fit	`enum`	''
hide-on-click-modal	预览模式下点击遮罩是否关闭	`boolean`	false
loading	浏览器加载策略，同原生 loading	`enum`	—
lazy	是否懒加载	`boolean`	false
scroll-container	懒加载时监听滚动的容器；默认取最近可滚动父级	`string` / `object`	—
alt	原生 `alt`	`string`	—
referrerpolicy	原生 referrerPolicy	`string`	—
crossorigin	原生 crossorigin	`enum`	—
preview-src-list	预览图片地址列表	`array`	[]
z-index	预览层 `z-index`	`number`	—
initial-index	初始预览索引，需小于列表长度	`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	预览初始缩放比例	`number`	1
min-scale	最小缩放比例	`number`	0.2
max-scale	最大缩放比例	`number`	7
show-progress	是否显示预览进度（与 `progress` 插槽配合）	`boolean`	false

图片事件

名称	说明	类型
load	同原生 `load`	`Function`
error	同原生 `error`	`Function`
switch	切换预览图片时触发	`Function`
close	点击关闭或开启 `hide-on-click-modal` 时点击遮罩关闭预览时触发	`Function`
show	预览打开时触发	`Function`

图片插槽

名称	说明	类型
placeholder	加载前占位	-
error	加载失败展示	-
image viewer slots	开启预览时，可使用下方 Image Viewer 全部插槽	-

图片暴露

名称	说明	类型
showPreview	手动打开预览	`Function`

图片预览 API

图片预览属性

名称	说明	类型	默认值
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	缩放速率	`number`	1.2
scale	预览初始缩放	`number`	1
min-scale	最小缩放比例	`number`	0.2
max-scale	最大缩放比例	`number`	7
close-on-press-escape	是否允许 ESC 关闭	`boolean`	true
show-progress	是否显示预览进度	`boolean`	false

图片预览事件

名称	说明	类型
close	点击关闭或 `hide-on-click-modal` 下点击遮罩时触发	`Function`
error	同原生 `error`	`Function`
switch	切换图片时触发	`Function`
rotate	旋转图片时触发	`Function`

图片预览插槽

名称	说明	类型
viewer	自定义预览区域内容	-
progress	自定义进度（优先级高于 `show-progress`）	`object`
toolbar	自定义工具栏	`object`
viewer-error	预览中某张图加载失败时的自定义内容	`object`

图片预览暴露

名称	说明	类型
setActiveItem	切换到指定索引	`Function`

类型声明

展开类型声明

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

Empty 空状态

Infinite Scroll 无限滚动

Image 图片 ​

基础用法 ​

占位内容 ​

加载失败 ​

懒加载 ​

图片预览 ​

手动打开预览 ​

自定义工具栏 ​

自定义进度 ​

图片 API ​

图片 属性 ​

图片 事件 ​

图片 插槽 ​

图片 暴露 ​

图片预览 API ​

图片预览 属性 ​

图片预览 事件 ​

图片预览 插槽 ​

图片预览 暴露 ​

类型声明 ​