RcImage 图片组件

RcImage 是一个功能丰富的图片展示组件，提供多种填充模式、形状样式、图片预览、懒加载等功能，满足各种图片展示场景的需求。

功能特性

✅ 支持多种填充模式：contain、cover、fill、none、scale-down
✅ 支持多种形状：方形、圆形、圆角
✅ 支持加载状态展示（自定义加载占位图）
✅ 支持加载失败展示（自定义错误占位图）
✅ 支持图片预览功能（放大、缩小、切换）
✅ 支持图片列表预览（左右切换）
✅ 支持图片描述文本
✅ 支持懒加载
✅ 支持自定义尺寸、边框、背景色
✅ 支持加载成功/失败回调

基础用法

普通图片

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200
})

使用本地资源

typescript

RcImage({ 
  imageSrc: $r('app.media.avatar'),
  imageWidth: 100,
  imageHeight: 100
})

图片填充模式

typescript

// 保持宽高比，完整显示（可能留白）
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 150,
  imageFit: 'contain'
})

// 保持宽高比，填满容器（可能裁剪）
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 150,
  imageFit: 'cover'
})

// 拉伸填满容器
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 150,
  imageFit: 'fill'
})

// 原始尺寸
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 150,
  imageFit: 'none'
})

// 取 contain 和 none 中较小的
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 150,
  imageFit: 'scale-down'
})

图片形状

typescript

// 方形
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 100,
  imageHeight: 100,
  imageShape: 'square'
})

// 圆形
RcImage({ 
  imageSrc: 'https://example.com/avatar.jpg',
  imageWidth: 100,
  imageHeight: 100,
  imageShape: 'circle'
})

// 圆角（可自定义圆角大小）
RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 100,
  imageHeight: 100,
  imageShape: 'round',
  imageRadius: 12
})

加载状态

自定义加载占位图

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200,
  showLoading: true,
  loadingIcon: $r('app.media.loading'),
  placeholderSize: 60,
  placeholderColor: '#409eff'
})

自定义错误占位图

typescript

RcImage({ 
  imageSrc: 'https://example.com/error.jpg',
  imageWidth: 200,
  imageHeight: 200,
  showError: true,
  errorIcon: $r('app.media.error'),
  placeholderSize: 60,
  placeholderColor: '#f56c6c'
})

图片预览

基础预览

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200,
  previewable: true
})

预览配置

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200,
  previewable: true,
  previewOptions: {
    showMask: true,           // 显示遮罩层
    showClose: true,          // 显示关闭按钮
    initialScale: 1,          // 初始缩放比例
    minScale: 0.5,            // 最小缩放比例
    maxScale: 3,              // 最大缩放比例
    onClose: () => {
      console.log('预览关闭')
    }
  }
})

图片列表预览

typescript

RcImage({ 
  imageSrc: 'https://example.com/image1.jpg',
  imageWidth: 200,
  imageHeight: 200,
  previewable: true,
  previewList: [
    'https://example.com/image1.jpg',
    'https://example.com/image2.jpg',
    'https://example.com/image3.jpg'
  ],
  previewIndex: 0  // 当前图片索引
})

图片描述

typescript

RcImage({ 
  imageSrc: 'https://example.com/scenery.jpg',
  imageWidth: 300,
  imageHeight: 200,
  showCaption: true,
  captionText: '美丽的风景照片'
})

边框和背景

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200,
  bgColor: '#f5f5f5',
  rcBorderWidth: 2,
  rcBorderColor: '#409eff',
  rcBorderStyle: BorderStyle.Solid
})

事件回调

typescript

RcImage({ 
  imageSrc: 'https://example.com/image.jpg',
  imageWidth: 200,
  imageHeight: 200,
  onImageClick: () => {
    console.log('图片被点击')
  },
  onImageLoad: () => {
    console.log('图片加载成功')
  },
  onImageError: (error: string) => {
    console.log('图片加载失败:', error)
  },
  onPreviewOpen: () => {
    console.log('预览打开')
  },
  onPreviewClose: () => {
    console.log('预览关闭')
  }
})

完整示例

typescript

@Entry
@Component
struct ImageDemo {
  build() {
    Column({ space: 20 }) {
      // 基础用法
      RcImage({ 
        imageSrc: 'https://example.com/image.jpg',
        imageWidth: 200,
        imageHeight: 200
      })

      // 圆形头像
      RcImage({ 
        imageSrc: 'https://example.com/avatar.jpg',
        imageWidth: 80,
        imageHeight: 80,
        imageShape: 'circle',
        imageFit: 'cover'
      })

      // 带预览的图片
      RcImage({ 
        imageSrc: 'https://example.com/photo.jpg',
        imageWidth: 300,
        imageHeight: 200,
        imageShape: 'round',
        imageRadius: 12,
        previewable: true,
        showCaption: true,
        captionText: '点击可预览'
      })

      // 图片列表
      Row({ space: 10 }) {
        ForEach([1, 2, 3, 4], (item: number) => {
          RcImage({ 
            imageSrc: `https://example.com/image${item}.jpg`,
            imageWidth: 80,
            imageHeight: 80,
            imageShape: 'round',
            imageRadius: 8,
            previewable: true,
            previewList: [
              'https://example.com/image1.jpg',
              'https://example.com/image2.jpg',
              'https://example.com/image3.jpg',
              'https://example.com/image4.jpg'
            ],
            previewIndex: item - 1
          })
        })
      }
    }
    .width('100%')
    .padding(20)
  }
}

API 文档

Props

参数	说明	类型	可选值	默认值
imageSrc	图片地址	`string \| Resource`	-	`''`
imageWidth	图片宽度	`RcStringNumber`	-	`100`
imageHeight	图片高度	`RcStringNumber`	-	`100`
imageFit	图片填充模式	`RcImageFit`	`contain` \| `cover` \| `fill` \| `none` \| `scale-down`	`cover`
imageShape	图片形状	`RcImageShape`	`square` \| `circle` \| `round`	`square`
imageRadius	圆角大小（imageShape='round' 时有效）	`RcStringNumber`	-	`8`
showLoading	是否显示加载中状态	`boolean`	-	`true`
showError	是否显示加载失败状态	`boolean`	-	`true`
loadingIcon	自定义加载占位图	`string \| Resource`	-	`''`
errorIcon	自定义失败占位图	`string \| Resource`	-	`''`
placeholderSize	加载占位图大小	`RcStringNumber`	-	`48`
placeholderColor	占位图颜色	`string \| Resource`	-	`#C0C4CC`
lazyLoad	是否懒加载	`boolean`	-	`false`
previewable	是否可预览	`boolean`	-	`false`
previewOptions	预览配置	`RcImagePreviewOptions`	-	`{}`
previewList	图片列表（用于预览切换）	`Array<string \| Resource>`	-	`[]`
previewIndex	当前图片在预览列表中的索引	`number`	-	`0`
showCaption	是否显示图片下方描述	`boolean`	-	`false`
captionText	图片描述文本	`string`	-	`''`
rcMargin	外边距	`Padding \| Length`	-	`0`
rcPadding	内边距	`Padding \| Length`	-	`0`
bgColor	背景颜色	`string \| Resource`	-	`#F5F7FA`
rcBorderStyle	边框样式	`BorderStyle`	-	`BorderStyle.Solid`
rcBorderWidth	边框宽度	`Length`	-	`0`
rcBorderColor	边框颜色	`string \| Resource`	-	`#DCDFE6`
onImageClick	点击事件	`() => void`	-	-
onImageLoad	图片加载成功回调	`() => void`	-	-
onImageError	图片加载失败回调	`(error: string) => void`	-	-
onPreviewOpen	图片预览打开回调	`() => void`	-	-
onPreviewClose	图片预览关闭回调	`() => void`	-	-

RcImagePreviewOptions

参数	说明	类型	默认值
showMask	是否显示遮罩层	`boolean`	`true`
showClose	是否显示关闭按钮	`boolean`	`true`
initialScale	初始缩放比例	`number`	`1`
minScale	最小缩放比例	`number`	`0.5`
maxScale	最大缩放比例	`number`	`3`
onClose	关闭回调	`() => void`	-

类型定义

typescript

// 图片填充模式
type RcImageFit = 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

// 图片形状
type RcImageShape = 'square' | 'circle' | 'round'

// 加载状态
type RcImageLoadStatus = 'loading' | 'success' | 'error'

使用场景

头像展示：用户头像、圆形图标
商品图片：商品列表、商品详情图
相册画廊：图片预览、图片切换
图片墙：多图展示、瀑布流
背景图：占位背景、装饰图片
缩略图：小尺寸预览、图片列表
广告图：轮播图、Banner图

注意事项

imageShape='circle' 时，建议 imageWidth 和 imageHeight 设置为相同值，以保证圆形效果
使用 previewable 时，建议设置合适的 imageFit 以优化预览体验
previewList 中的图片顺序应与展示顺序一致，previewIndex 从 0 开始
自定义占位图时，建议图片尺寸与 placeholderSize 相匹配
lazyLoad 功能需要在列表滚动场景中使用才有意义
预览弹窗会覆盖在最上层（zIndex: 1000），注意与其他浮层的层级关系
网络图片加载时会自动显示加载状态，本地资源通常加载很快，可能看不到加载状态
图片加载失败时，如果设置了 showError=false，将不显示任何内容

RcImage 图片组件 ​

功能特性 ​

基础用法 ​

普通图片 ​

使用本地资源 ​

图片填充模式 ​

图片形状 ​

加载状态 ​

自定义加载占位图 ​

自定义错误占位图 ​

图片预览 ​

基础预览 ​

预览配置 ​

图片列表预览 ​

图片描述 ​

边框和背景 ​

事件回调 ​

完整示例 ​

API 文档 ​

Props ​

RcImagePreviewOptions ​

类型定义 ​

使用场景 ​

注意事项 ​

RcImage 图片组件

功能特性

基础用法

普通图片

使用本地资源

图片填充模式

图片形状

加载状态

自定义加载占位图

自定义错误占位图

图片预览

基础预览

预览配置

图片列表预览

图片描述

边框和背景

事件回调

完整示例

API 文档

Props

RcImagePreviewOptions

类型定义

使用场景

注意事项