Skip to content

Image 图片

该组件是一款基于 uniapp 的 image 组件优化而来,支持图片懒加载,预加载,加载后的过渡效果,加载中与加载失败的占位符等。

解决了一大痛点: 懒加载不生效的问题,并且手动支持了 app、weixin、h5。

关于懒加载(默认使用懒加载)

由于示例使用的是同一张图片,即使懒加载列表很长,也会因为已有这张图的缓存加载很快,有可能看不出来懒加载效果。

因此我们通过设置 minLoadginShowTime 属性来规定加载中状态的最小显示时间(默认50,单位ms),可以让您更好查看懒加载的效果(推荐您扫描上方二维码直接查看效果)

上线项目使用时推荐您将 minLoadginShowTime 设置为0,以此来优化性能。

平台兼容性

App(vue)App(nvue)H5小程序VUE2VUE3

基本使用

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

vue
<template>
  <wu-image
    :show-loading="true"
    :src="src"
    width="80px"
    height="80px"
    @click="click"
  ></wu-image>
</template>

<script>
export default {
  data() {
    return {
      src: "https://wuui.cn/1.jpeg",
    };
  },
};
</script>
<template>
  <wu-image
    :show-loading="true"
    :src="src"
    width="80px"
    height="80px"
    @click="click"
  ></wu-image>
</template>

<script>
export default {
  data() {
    return {
      src: "https://wuui.cn/1.jpeg",
    };
  },
};
</script>

图片形状

  • 通过 shape 参数设置图片的形状,circle 为圆形,square 为方形
  • 如果为方形时,还可以通过 radius 属性设置圆角值
vue
<wu-image src="https://wuui.cn/1.jpeg" shape="circle"></wu-image>
<wu-image src="https://wuui.cn/1.jpeg" shape="circle"></wu-image>

剪裁模式

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

vue
<wu-image src="https://wuui.cn/1.jpeg" mode="widthFix"></wu-image>
<wu-image src="https://wuui.cn/1.jpeg" mode="widthFix"></wu-image>

懒加载

注意: 仅对 app、h5、微信小程序,默认开启。

lazy-load 用于是否启用懒加载

lazy-load-root-margin 用于设置懒加载根边距 设置负数则是进入视图指定距离后显示 正数则是离视图多远时显示

vue
<wu-image
  v-for="num in 30"
  :key="num"
  src="https://wuui.cn/1.jpeg"
  width="80px"
  height="80px"
  :lazy-load="true"
  :lazy-load-root-margin="-5"
></wu-image>
<wu-image
  v-for="num in 30"
  :key="num"
  src="https://wuui.cn/1.jpeg"
  width="80px"
  height="80px"
  :lazy-load="true"
  :lazy-load-root-margin="-5"
></wu-image>

加载中提示

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

html
<wu-image src="https://wuui.cn/1.jpeg">
  <template v-slot:loading>
    <wu-loading-icon color="red"></wu-loading-icon>
  </template>
</wu-image>
<wu-image src="https://wuui.cn/1.jpeg">
  <template v-slot:loading>
    <wu-loading-icon color="red"></wu-loading-icon>
  </template>
</wu-image>

加载错误提示

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

html
<wu-image src="https://wuui.cn/1.jpeg">
  <template v-slot:error>
    <view style="font-size: 24rpx;">加载失败</view>
  </template>
</wu-image>
<wu-image src="https://wuui.cn/1.jpeg">
  <template v-slot:error>
    <view style="font-size: 24rpx;">加载失败</view>
  </template>
</wu-image>

淡入动画

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

  • 通过 fade 参数配置是否开启动画效果
  • 通过 duration 参数配置动画的过渡时间,单位ms
vue
<wu-image src="https://wuui.cn/1.jpeg" :fade="true" duration="450"></wu-image>
<wu-image src="https://wuui.cn/1.jpeg" :fade="true" duration="450"></wu-image>

事件冒泡

默认情况下,组件是允许内部向外事件冒泡的,因为很多情况下,我们都希望点击图片,同时图片所在的父元素的点击事件也能触发。

如果您想避免事件冒泡,那么您可以在组件外面嵌套一个 view ,同时给它加上 @tap.stop 即可。

html
<!-- 点击图片将不会触发clickHandler -->
<view @tap="clickHandler">
	<view @tap.stop>
		<wu-image src="https://wuui.cn/1.jpeg"></wu-image>
	</view>
</view>
<!-- 点击图片将不会触发clickHandler -->
<view @tap="clickHandler">
	<view @tap.stop>
		<wu-image src="https://wuui.cn/1.jpeg"></wu-image>
	</view>
</view>

API

Button Props

属性名说明类型默认值可选值
src图片地址,强烈建议使用绝对或者网络路径String--
mode裁剪模式,见上方说明StringaspectFill-
width宽度,单位任意,如果为数值,默认单位pxString / Number300-
height高度,单位任意,如果为数值,默认单位pxString / Number225-
shape图片形状,circle-圆形,square-方形Stringsquaresquare / square
radius圆角,默认单位pxString / Number0-
lazyLoad是否懒加载,仅对 app、h5、微信小程序Booleantruetrue / false
lazyLoadRootMargin懒加载根边距 设置负数则是进入视图指定距离后显示 正数则是离视图多远时显示String / Number-5-
minLoadginShowTime加载中状态的最小显示时间(单位ms)String / Number50-
showMenuByLongpress是否开启长按图片显示识别小程序码菜单,仅微信小程序有效Booleantruetrue / false
loadingIcon加载中的图标,或者小图片Stringphoto-
errorIcon加载失败的图标,或者小图片Stringinfo-circle-
showLoading是否显示加载中的图标或者自定义的slotBooleantruetrue / false
showError是否显示加载错误的图标或者自定义的slotBooleantruetrue / false
fade是否需要淡入效果Booleantruetrue / false
webp只支持网络资源,只对微信小程序有效Booleanfalsetrue / false
duration搭配 fade 参数的过渡时间,单位msString / Number500-
bgColor背景颜色,用于深色页面加载图片时,为了和背景色融合String / Number#f3f4f6-

Button Slot

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

Button Events

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