更新记录

1.0.9（2025-07-19） 下载此版本

优化

1.0.8（2025-07-10） 下载此版本

优化

1.0.7（2025-07-07） 下载此版本

1

平台兼容性

uni-app(4.06)

其他

x-image 组件使用说明

概述

基于 uni-app 的 image 组件进行封装，提供了图片懒加载、缓存，增加图片二次加载速度，极大的减少 CDN 流量资源消耗

主要特性

• 🖼️ 图片懒加载：支持占位图和滚动触发加载
• 💾 图片缓存：自动缓存图片，提升加载性能

基础用法

简单使用

<template>
    <!-- 传入 placeholder-src 和 scrollTop 使用懒加载-->
  <x-image src="https://example.com/image.jpg" placeholder-src="https://example.com/loading.jpg"  :scroll-top="scrollTop" />
</template>

设置尺寸

<template>
  <!-- 方式1：使用 size 属性 -->
  <x-image 
    src="https://example.com/image.jpg" 
    size="200rpx"
    placeholder-src="https://example.com/loading.jpg"
    :scroll-top="scrollTop"
  />

  <!-- 方式2：分别设置宽高 -->
  <x-image 
    src="https://example.com/image.jpg" 
    width="200rpx" 
    height="200rpx"
    placeholder-src="https://example.com/loading.jpg"
    :scroll-top="scrollTop"
  />
</template>

图片懒加载 (传入 placeholder-src 低分辨率图地址开启懒加载, scrollTop 必须传入页面或 scroll-view 滚动距离)

<template>
  <x-image 
    src="https://example.com/image.jpg"
    placeholder-src="https://example.com/placeholder.jpg"
    :scroll-top="scrollTop"
    :scroll-area-height="scrollAreaHeight"
  />
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0,
      scrollAreaHeight: 0
    }
  },
  mounted() {
    // 注意：不同平台滚动区域高度有差异自行调式
    this.scrollAreaHeight = uni.getSystemInfoSync().windowHeight
  },
  onPageScroll(e){
    this.scrollTop = e.scrollTop
  }
}
</script>

属性说明

基础属性

尺寸属性

滚动相关属性

样式属性

图片模式说明，更多详见

事件说明

使用示例

在 scroll-view 中使用懒加载

<template>
  <scroll-view 
    scroll-y 
    @scroll=""
    style="height: 400px;"
  >
    <x-image 
      v-for="(item, index) in imageList" 
      :key="index"
      :src="item.url"
      :placeholder-src="item.placeholder"
      :scroll-top="scrollTop"
      :scroll-area-height="400"
      :offset-top="0"
      size="200rpx"
      @load="onImageLoad"
      @error="onImageError"
    />
  </scroll-view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0,
      imageList: [
        {
          url: 'https://example.com/image1.jpg',
          placeholder: 'https://example.com/placeholder1.jpg'
        },
        {
          url: 'https://example.com/image2.jpg',
          placeholder: 'https://example.com/placeholder2.jpg'
        }
      ]
    }
  },
  methods: {
    (e) {
      this.scrollTop = e.detail.scrollTop
    },
    onImageLoad(e) {
      console.log('图片加载成功', e)
    },
    onImageError(e) {
      console.log('图片加载失败', e)
    }
  }
}
</script>

自定义样式

<template>
  <x-image 
    src="https://example.com/image.jpg"
    custom-class="my-image"
    size="200rpx"
  />
</template>

<style>
.my-image {
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
</style>

禁用图片缓存

<template>
  <x-image 
    src="https://example.com/image.jpg"
    :cache-image="false"
    size="200rpx"
  />
</template>

注意事项

1. 懒加载使用：需要传入 placeholder-src 才会启用懒加载功能
2. 滚动监听：在 scroll-view 中使用时，需要正确设置 offset-top 和 offset-left
3. 图片缓存：默认开启图片缓存，如不需要可设置 cache-image 为 false
4. 尺寸优先级：width/height 优先级高于 size 属性
5. 平台差异：不同平台的滚动区域高度可能有差异，建议根据实际情况调整