uv-ui

# Image 图片

✈

组件名：uv-image

点击下载&安装 (opens new window)

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

我们在图片中加入了observer懒加载的思想，由于官方提供的lazyLoad懒加载有些限制，可能在实际项目中并不能满足需求，observer可以真正意义上实现懒加载，具体使用会在下面有介绍。

我们推荐您在任何使用图片场景的地方，都优先考虑使用这个小巧，uv-image精致而实用的组件。

# 平台兼容性

App（vue） App（nvue） H5 小程序 VUE2 VUE3
√ √ √ √ √ √

# 基本使用

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

<template>
	<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg" width="80px" height="80px"></uv-image>
</template>

# 图片裁剪、缩放的模式

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

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

# 图片形状

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

# 懒加载

注意：此功能只对微信小程序、App、百度小程序、字节跳动小程序有效，且只针对page与scroll-view下的image有效，默认开启。

<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg" :lazy-load="true"></uv-image>

# observer懒加载

  • 通过observeLazyLoad为true即可开启该功能，效果：在该图片滑动到可视范围内的时候才会去请求加载图片。
  • 注意：此功能在nvue页面不生效，因为nvue并不支持uni.createIntersectionObserver()，默认关闭。
<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg" :observeLazyLoad="true"></uv-image>

# 加载中提示

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

<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg">
  <template v-slot:loading>
    <uv-loading-icon color="red"></uv-loading-icon>
  </template>
</uv-image>

# 加载错误提示

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

<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg">
	<template v-slot:error>
		<view style="font-size: 24rpx;">加载失败</view>
	</template>
</uv-image>

# 淡入动画

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

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

# 事件冒泡

默认情况下，组件是允许内部向外事件冒泡的，因为很多情况下，我们都希望点击图片，同时图片所在的父元素的点击事件也能触发。
如果您想避免事件冒泡，那么您可以在组件外面嵌套一个view，同时给它加上@tap.stop即可。

<!-- 点击图片将不会触发clickHandler -->
<view @tap="clickHandler">
	<view @tap.stop>
		<uv-image src="https://cdn.uviewui.com/uview/album/1.jpg"></uv-image>
	</view>
</view>

# 完整示例

完整示例下载地址

https://ext.dcloud.net.cn/plugin?name=uv-ui (opens new window)

# API

# Image Props

参数 说明 类型 默认值 可选值
src 图片地址，强烈建议使用绝对或者网络路径 String - -
mode 裁剪模式，见上方说明 String aspectFill -
width 宽度，单位任意，如果为数值，默认单位px(rpx) String | Number 300 -
height 高度，单位任意，如果为数值，默认单位px(rpx) String | Number 225 -
shape 图片形状，circle - 圆形，square - 方形 String square square
radius 圆角，默认单位px String | Number 0 -
lazyLoad 是否懒加载，仅微信小程序、App、百度小程序、字节跳动小程序有效 Boolean true | false -
observeLazyLoad 是否observer懒加载，在该图片滑动到可视范围内的时候才会去请求加载图片。nvue页面不生效。 Boolean false true | false
showMenuByLongpress 是否开启长按图片显示识别小程序码菜单，仅微信小程序有效 Boolean true -
loadingIcon 加载中的图标，或者小图片 String photo -
errorIcon 加载失败的图标，或者小图片 String error-circle -
showLoading 是否显示加载中的图标或者自定义的slot Boolean true true | false
showError 是否显示加载错误的图标或者自定义的slot Boolean true true | false
fade 是否需要淡入效果 Boolean true true | false
webp 只支持网络资源，只对微信小程序有效 Boolean false true | false
duration 搭配fade参数的过渡时间，单位ms String | Number 500 -
bgColor 背景颜色，用于深色页面加载图片时，为了和背景色融合 String #f3f4f6 -
cellChild 是否属于cell节点下。nvue模式下的该组件在cell或uv-list等组件下使用，该值最好是设置成true，避免回收后不显示的BUG。 Boolean false true | false
customStyle 自定义样式 Object - -

# Image Slots

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

# Image Events

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

← Transition 动画 →