更新记录

1.0.0（2025-10-16） 下载此版本

• 初始版本发布

平台兼容性

uni-app(4.72)

oui-image

通用的 uniapp 图片加载组件，支持小程序、App、Web 等全平台，提供简洁高效的图片加载体验。

特性

• 多种显示模式：支持普通图片和背景图模式
• 骨架屏加载：内置现代化的渐进式加载动画
• 懒加载支持：可视区域内才加载图片，提升性能
• 静默错误处理：加载失败时保持界面简洁
• 备用图片：自动切换备用图片机制
• 样式定制：支持圆角、边框、阴影等样式

安装

# 通过 uni_modules 安装（推荐）
# 直接将 oui-image 文件夹放入 src/uni_modules/ 目录下即可

快速开始

基础用法

<template>
  <!-- 基础图片 -->
  <oui-image src="/static/images/demo.jpg" width="200px" height="150px" />

  <!-- 圆角图片 -->
  <oui-image src="/static/images/demo.jpg" width="100px" height="100px" radius="8px" />

  <!-- 圆形头像 -->
  <oui-image src="/static/images/avatar.jpg" width="80px" height="80px" radius="50%" />
</template>

图片模式

<template>
  <!-- 不同的图片裁剪模式 -->
  <oui-image src="/static/images/demo.jpg" width="200px" height="150px" image-mode="aspectFit" />
  <oui-image src="/static/images/demo.jpg" width="200px" height="150px" image-mode="aspectFill" />
  <oui-image src="/static/images/demo.jpg" width="200px" height="150px" image-mode="scaleToFill" />
</template>

背景图模式

<template>
  <oui-image
    src="/static/images/banner.jpg"
    mode="background"
    width="100%"
    height="200px"
    radius="12px"
  >
    <view class="content">
      <text class="title">标题内容</text>
      <text class="subtitle">副标题内容</text>
    </view>
  </oui-image>
</template>

<style>
.content {
  padding: 20px;
  color: white;
}
.title {
  font-size: 24px;
  font-weight: bold;
}
.subtitle {
  font-size: 16px;
  opacity: 0.8;
}
</style>

高级功能

懒加载

<template>
  <!-- 懒加载图片 -->
  <oui-image
    src="/static/images/demo.jpg"
    width="100%"
    height="200px"
    lazy-load
    :lazy-offset="100"
  />
</template>

错误处理与备用图片

<template>
  <!-- 带备用图片的错误处理 -->
  <oui-image
    src="/static/images/demo.jpg"
    fallback="/static/images/placeholder.jpg"
    width="200px"
    height="150px"
  />
</template>

样式定制

<template>
  <!-- 自定义样式 -->
  <oui-image
    src="/static/images/demo.jpg"
    width="150px"
    height="150px"
    radius="12px"
    border="2px solid #007aff"
    shadow="0 4px 12px rgba(0, 0, 0, 0.15)"
  />

  <!-- 组合样式效果 -->
  <oui-image
    src="/static/images/demo.jpg"
    width="120px"
    height="120px"
    radius="60px"
    border="3px solid #ffffff"
    shadow="0 8px 24px rgba(0, 122, 255, 0.3)"
  />
</template>

事件处理

<template>
  <oui-image
    src="/static/images/demo.jpg"
    width="200px"
    height="150px"
    @click="handleClick"
    @load="handleLoad"
    @error="handleError"
  />
</template>

<script setup>
const handleClick = (event) => {
  console.log('图片被点击', event);
  uni.showToast({ title: '图片被点击', icon: 'none' });
};

const handleLoad = (event) => {
  console.log('图片加载成功', event.detail);
};

const handleError = (event) => {
  console.log('图片加载失败', event.detail);
  uni.showToast({ title: '图片加载失败', icon: 'error' });
};
</script>

API 文档

Props

image-mode 可选值

Events

Slots

注意事项

1. 图片路径：确保图片路径正确，支持相对路径、绝对路径和网络地址
2. 懒加载性能：启用懒加载时，图片会在进入可视区域时才开始加载，建议为长列表启用
3. 背景图模式：在背景图模式下，可以在图片上叠加其他内容，适合制作卡片和横幅
4. 错误处理：组件采用静默错误处理，建议设置备用图片提升用户体验
5. 样式优先级：自定义样式会覆盖组件默认样式，请注意样式优先级