zx-image 图片组件

介绍

zx-image 是一个基于 uni-app 的增强型图片组件，提供了图片懒加载、占位图、加载失败显示等功能，适用于各类 uni-app 项目中的图片展示需求。

特性

• 支持图片懒加载（自定义实现和原生懒加载）
• 支持图片加载动画效果
• 支持占位图和背景色
• 支持加载失败时显示替代图片
• 支持圆角设置
• 兼容各端小程序和 App

安装方法

将组件复制到项目的 components 目录下即可使用。

基本用法

<template>
  <view>
    <zx-image
      src="https://example.com/image.jpg"
      width="300rpx"
      height="200rpx"
      radius="10rpx"
    ></zx-image>
  </view>
</template>

<script>
import zxImage from '@/components/zx-image/zx-image.vue';

export default {
  components: {
    zxImage
  }
}
</script>

属性说明

| 属性名 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | src | String | '' | 图片路径 | | srcParams | String | '' | 图片链接附加参数，如七牛云图片处理参数 | | placeholder | String | '' | 占位图路径 | | backgroundColor | String | '#f1f1f1' | 占位背景色，placeholder有值时失效 | | mode | String | 'aspectFill' | 图片的裁剪模式，参考image组件mode属性 | | fadeShow | Boolean | true | 图片显示动画效果，无占位图时有效 | | webp | Boolean | false | 默认不解析 webP 格式，只支持网络资源 | | showMenuByLongpress | Boolean | false | 开启长按图片显示识别小程序码菜单（微信小程序2.7.0+） | | draggable | Boolean | true | 鼠标长按是否能拖动图片（仅H5平台 3.1.1+） | | width | String | '230rpx' | 图片宽度 | | height | String | '180rpx' | 图片高度，如果高度设置为auto，mode值需要设置为widthFix | | radius | String | '0rpx' | 图片圆角值 | | bottom | Number/String | 50 | 节点布局区域的下边界，目标节点区域以下 bottom(px) 时触发懒加载 | | disconnect | Boolean | false | 是否停止监听，设置为true时懒加载将不再触发 | | index | Number | 0 | 图片在列表中的索引值 | | lazyLoad | Boolean | true | 是否开启懒加载（自定义实现） | | nativeLazyLoad | Boolean | false | 是否使用原生的lazy-load属性（仅微信小程序、百度小程序、抖音小程序、飞书小程序支持） | | padding | String | '0rpx' | 内边距 | | errorImage | String | '' | 加载失败时显示的图片 |

事件说明

| 事件名 | 说明 | 返回参数 | | --- | --- | --- | | @error | 当错误发生时触发 | {detail: 图片加载错误信息, index: 索引值} | | @load | 当图片加载完成时触发 | {detail: {width: 图片宽度, height: 图片高度}, index: 索引值} | | @click | 点击图片时触发 | {index: 索引值} |

方法说明

组件对外暴露的方法，可通过 ref 调用：

| 方法名 | 说明 | 参数 | | --- | --- | --- | | loadImage | 手动触发加载图片 | 无 |

使用示例

基础用法

<zx-image src="/static/images/example.jpg"></zx-image>

设置圆角

<zx-image src="/static/images/example.jpg" radius="20rpx"></zx-image>

使用占位图

<zx-image 
  src="/static/images/example.jpg" 
  placeholder="/static/images/placeholder.jpg"
></zx-image>

错误图片

<zx-image 
  src="/static/images/example.jpg" 
  errorImage="/static/images/error.jpg"
></zx-image>

列表懒加载

<template>
  <scroll-view scroll-y>
    <view v-for="(item, index) in imageList" :key="index">
      <zx-image 
        :src="item.src" 
        :index="index"
        @load="onImageLoad"
        @error="onImageError"
        @click="onImageClick"
      ></zx-image>
    </view>
  </scroll-view>
</template>

<script>
export default {
  data() {
    return {
      imageList: [
        { src: '/static/images/1.jpg' },
        { src: '/static/images/2.jpg' },
        { src: '/static/images/3.jpg' }
        // ...更多图片
      ]
    }
  },
  methods: {
    onImageLoad(e) {
      console.log('图片加载成功', e);
    },
    onImageError(e) {
      console.log('图片加载失败', e);
    },
    onImageClick(e) {
      console.log('点击了图片', e.index);
    }
  }
}
</script>

手动触发加载

<template>
  <view>
    <zx-image 
      ref="myImage"
      src="/static/images/example.jpg" 
      :disconnect="true"
    ></zx-image>
    <button @click="loadImage">加载图片</button>
  </view>
</template>

<script>
export default {
  methods: {
    loadImage() {
      this.$refs.myImage.loadImage();
    }
  }
}
</script>

提示

• 使用 widthFix 模式时，建议将 height 设置为 'auto'
• 大量图片列表建议使用懒加载功能，提升性能
• 在 App 和 H5 端，自定义懒加载使用 IntersectionObserver API 实现
• 在小程序中，可以选择使用原生懒加载（nativeLazyLoad=true）或自定义懒加载