更新记录

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

优化

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

1

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

优化

平台兼容性

uni-app

其他

x-image 组件使用说明

概述

x-image 是一个功能强大的图片组件，支持图片懒加载、缓存、多种显示模式等特性。

主要特性

• 🖼️ 图片懒加载：支持占位图和滚动触发加载
• 💾 图片缓存：自动缓存图片，提升加载性能
• 🔄 滚动监听：支持垂直、水平、双向滚动监听

基础用法

简单使用

<template>
  <x-image src="https://example.com/image.jpg" />
</template>

设置尺寸

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

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

图片懒加载

<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. 平台差异：不同平台的滚动区域高度可能有差异，建议根据实际情况调整