uView Next
4.0.105

外观

Image 图片

约 1146 字大约 4 分钟

2025-10-31

此组件为 uni-app 的image组件的加强版，在继承了原有功能外，还支持淡入动画、加载中、加载失败提示、圆角值和形状等。

基本使用

配置图片的width宽和height高，以及src路径即可使用。

<un-image :src="src" :width="80" :height="80"></un-image>

图片形状

  • 通过shape参数设置图片的形状，circle为圆形，square为方形
  • 如果为方形时，还可以通过round属性设置圆角值
<un-image src="https://uviewui.com/album/1.jpg" shape="circle"></un-image>

裁剪模式

通过mode参数配置填充模式，此模式用法与 uni-app 的image组件的mode参数完全一致，详见：Image

<un-image src="https://uviewui.com/album/1.jpg" mode="widthFix"></un-image>

图片预览

通过设置previewSrcList参数，可以实现图片预览功能，点击图片时会展示预览画廊。

<template>
  <un-image
    v-for="(item, index) in imageList"
    :key="index"
    :src="item"
    :previewSrcList="imageList"
    :previewIndex="index"
    shape="circle"
    width="80px"
    height="80px"
  ></un-image>
</template>

<script setup lang="uts">
  import { ref } from 'vue'

  const imageList = ref<Array<string>>([
    'https://pic.qqans.com/up/2023-4/16822091397172911.jpg',
    'https://pic.qqans.com/up/2023-4/16822091391206647.jpg',
    'https://pic.qqans.com/up/2023-4/16822091396280683.jpg'
  ])
</script>

如果需要从指定索引开始预览，可以设置previewIndex参数：

<template>
  <un-image
    :src="imageList[0]"
    :previewSrcList="imageList"
    :previewIndex="2"
    width="80px"
    height="80px"
  ></un-image>
</template>

<script setup lang="uts">
  import { ref } from 'vue'

  const imageList = ref<Array<string>>([
    'https://pic.qqans.com/up/2023-4/16822091397172911.jpg',
    'https://pic.qqans.com/up/2023-4/16822091391206647.jpg',
    'https://pic.qqans.com/up/2023-4/16822091396280683.jpg'
  ])
</script>

加载中提示

图片加载过程中，为加载中状态(默认显示一个小图标)，可以通过loading自定义插槽，结合 uView 的un-loading组件，实现加载的动画效果。

<un-image src="https://uviewui.com/album/1.jpg">
  <template #loading>
    <un-loading color="red"></un-loading>
  </template>
</un-image>

加载错误提示

图片加载失败时，默认显示一个错误提示图标，可以通过error自定义插槽，实现个性化的提示方式。

<un-image src="https://uviewui.com/album/1.jpg">
  <template #error>
    <text>加载失败</text>
  </template>
</un-image>

淡入动画

组件自带了加载完成时的淡入动画效果：

  • 通过fade参数配置是否开启动画效果
  • 通过duration参数配置动画的过渡时间，单位 ms
<un-image
  src="https://uviewui.com/album/1.jpg"
  :fade="true"
  :duration="450"
></un-image>

裁剪模式

通过mode参数配置填充模式，此模式用法与 uni-app 的image组件的mode参数完全一致，详见：Image

<un-image src="https://uviewui.com/album/1.jpg" mode="widthFix"></un-image>

API

Props

参数说明类型默认值
src图片地址，强烈建议使用绝对或者网络路径String-
mode裁剪模式，见上方说明StringaspectFill
width宽度，单位任意，如果为数值，默认单位 pxString | Number300
height高度，单位任意，如果为数值，默认单位 pxString | Number225
shape图片形状，circle-圆形，square-方形
Enum
square
round设置圆角值，默认单位 pxString | Number0
fade是否显示淡入动画效果Booleantrue
lazyLoad是否懒加载，仅微信小程序、App、百度小程序、字节跳动小程序有效Booleantrue
previewSrcList图片预览数组Array<string>-
previewIndex图片预览索引Number0
showMenuByLongpress是否开启长按图片显示识别小程序码菜单，仅微信小程序有效Booleantrue
loadingIcon加载中的图标，或者小图片Stringphoto
errorIcon加载失败的图标，或者小图片Stringerror-circle
showLoading是否显示加载中的图标或者自定义的 slotBooleanfalse
showError是否显示加载错误的图标或者自定义的 slotBooleanfalse
fade是否需要淡入效果Booleanfalse
webp只支持网络资源，只对微信小程序有效Booleanfalse
duration搭配fade参数的过渡时间，单位 msString | Number500
bgColor背景颜色，用于深色页面加载图片时，为了和背景色融合String#f3f4f6
customStyle自定义样式String | Object-

Slot

名称说明
loading自定义加载中的提示内容
error自定义失败的提示内容

Events

事件名说明回调参数
click点击图片时触发-
error图片加载失败时触发err: 错误信息
load图片加载成功时触发-

Scss 变量

变量名默认值说明
$un-image-transition-duration0.5s图片过渡动画时长
$un-image-transition-timing-functionease-in-out图片过渡动画函数
$un-image-loading-bg-color$bg-color-lighter图片加载中背景色
$un-image-loading-z-index10图片加载中层级
$un-image-error-bg-color$bg-color-lighter图片加载失败背景色
$un-image-error-z-index10图片加载失败层级

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next