外观
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 | 裁剪模式,见上方说明 | String | aspectFill |
| width | 宽度,单位任意,如果为数值,默认单位 px | String | Number | 300 |
| height | 高度,单位任意,如果为数值,默认单位 px | String | Number | 225 |
| shape | 图片形状,circle-圆形,square-方形 | Enum | square |
| round | 设置圆角值,默认单位 px | String | Number | 0 |
| fade | 是否显示淡入动画效果 | Boolean | true |
| lazyLoad | 是否懒加载,仅微信小程序、App、百度小程序、字节跳动小程序有效 | Boolean | true |
| previewSrcList | 图片预览数组 | Array<string> | - |
| previewIndex | 图片预览索引 | Number | 0 |
| showMenuByLongpress | 是否开启长按图片显示识别小程序码菜单,仅微信小程序有效 | Boolean | true |
| loadingIcon | 加载中的图标,或者小图片 | String | photo |
| errorIcon | 加载失败的图标,或者小图片 | String | error-circle |
| showLoading | 是否显示加载中的图标或者自定义的 slot | Boolean | false |
| showError | 是否显示加载错误的图标或者自定义的 slot | Boolean | false |
| fade | 是否需要淡入效果 | Boolean | false |
| webp | 只支持网络资源,只对微信小程序有效 | Boolean | false |
| duration | 搭配fade参数的过渡时间,单位 ms | String | Number | 500 |
| bgColor | 背景颜色,用于深色页面加载图片时,为了和背景色融合 | String | #f3f4f6 |
| customStyle | 自定义样式 | String | Object | - |
Slot
| 名称 | 说明 |
|---|---|
| loading | 自定义加载中的提示内容 |
| error | 自定义失败的提示内容 |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 点击图片时触发 | - |
| error | 图片加载失败时触发 | err: 错误信息 |
| load | 图片加载成功时触发 | - |
Scss 变量
| 变量名 | 默认值 | 说明 |
|---|---|---|
| $un-image-transition-duration | 0.5s | 图片过渡动画时长 |
| $un-image-transition-timing-function | ease-in-out | 图片过渡动画函数 |
| $un-image-loading-bg-color | $bg-color-lighter | 图片加载中背景色 |
| $un-image-loading-z-index | 10 | 图片加载中层级 |
| $un-image-error-bg-color | $bg-color-lighter | 图片加载失败背景色 |
| $un-image-error-z-index | 10 | 图片加载失败层级 |
提示
组件内部默认使用 scss 变量,如需修改,请查看 scss 变量使用 文档
