跳到主要内容HarmonyOS6 RcImage 组件实战指南与案例解析 | 极客日志TypeScript大前端
HarmonyOS6 RcImage 组件实战指南与案例解析
档提供 RcImage 组件在 HarmonyOS6 开发中的完整使用指南。涵盖六大核心场景:基础用法、填充模式、图片形状、加载状态等。通过代码示例深入展示组件功能特性,包括网络图片加载、本地资源引用、尺寸控制、fit 模式选择(contain/cover/fill 等)、形状设置(方形/圆形/圆角)及加载失败处理。帮助开发者快速掌握图片展示与交互的最佳实践,提升鸿蒙应用 UI 开发效率。
晚风告白4 浏览 文档说明
本文档提供 RcImage 组件在 HarmonyOS6 开发中的完整使用指南。通过核心场景和实战案例,深入展示组件的各项功能特性,帮助开发者快速掌握图片展示与交互的最佳实践。
一:实战案例集架构设计
1.1 整体架构概览
RcImages 实战案例集采用 Tab 切换式架构,将核心功能模块进行分类展示,便于开发者快速定位和学习特定功能。

@Entry
@Component
struct RcImages {
@State currentTab: number = 0
@State imageList: string[] = [
'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500'
]
build() {
Scroll() {
Column({ space: 20 }) {
Text('RcImage 组件演示').fontSize(24).fontWeight(FontWeight.Bold).width('100%').textAlign(TextAlign.Center).margin({ top: 20, bottom: 10 })
Tabs({ index: $$this.currentTab }) {
TabContent() { this.BasicUsage() }.tabBar('基础用法')
TabContent() { this.() }.()
() { .() }.()
() { .() }.()
() { .() }.()
() { .() }.()
}.(.).().()
}.().()
}.().().()
}
}
微信扫一扫,关注极客日志
微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
相关免费在线工具
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
- Markdown转HTML
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
- HTML转Markdown
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
- JSON 压缩
通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
- JSON美化和格式化
将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online
FitModes
tabBar
'填充模式'
TabContent
this
ImageShapes
tabBar
'图片形状'
TabContent
this
LoadingStates
tabBar
'加载状态'
TabContent
this
PreviewDemo
tabBar
'图片预览'
TabContent
this
BorderStyles
tabBar
'边框样式'
barMode
BarMode
Scrollable
width
'100%'
height
'100%'
width
'100%'
padding
16
width
'100%'
height
'100%'
backgroundColor
'#F5F7FA'
1.2 架构设计特点
| 设计特点 | 实现方式 | 优势 |
|---|
| 模块化展示 | Tabs + Builder 模式 | 功能分类清晰,易于维护 |
| 状态管理 | @State 装饰器 | 响应式 Tab 切换 |
| 数据集中 | imageList 数组 | 复用图片资源,减少重复 |
| 滚动支持 | Scroll 容器 | 适配长内容展示 |
| 响应式布局 | 百分比宽度 | 适配不同屏幕尺寸 |
1.3 六大功能模块
- 基础用法 (BasicUsage):普通图片展示、本地资源加载、自定义尺寸、带描述文本
- 填充模式 (FitModes):contain、cover、fill、scale-down、none
- 图片形状 (ImageShapes):方形、圆形、圆角 (可自定义)
- 加载状态 (LoadingStates):正常加载、加载失败、自定义占位图、隐藏加载状态
- 图片预览 (PreviewDemo):单张图片预览、图片列表预览、缩放与切换
- 边框样式 (BorderStyles):实线边框、虚线边框、点状边框、边框 + 形状组合
二:基础用法实战
2.1 普通图片展示
@Builder BasicUsage() {
Scroll() {
Column({ space: 20 }) {
this.SectionTitle('普通图片')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200
})
}.width('100%').padding(16)
}
}
- 使用
imageSrc 指定网络图片地址
- 通过
imageWidth 和 imageHeight 控制显示尺寸
- 默认填充模式为
cover,适合展示类场景
2.2 本地资源加载
this.SectionTitle('本地资源 (示例)')
RcImage({
imageSrc: $r('app.media.startIcon'),
imageWidth: 100,
imageHeight: 100
})
- 使用
$r() 语法加载本地资源
- 支持 PNG、JPG、SVG 等多种格式
- 本地资源无需处理加载状态
2.3 自定义尺寸
this.SectionTitle('自定义尺寸')
Row({ space: 10 }) {
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500', imageWidth: 80, imageHeight: 80 })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500', imageWidth: 120, imageHeight: 120 })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500', imageWidth: 160, imageHeight: 160 })
}.width('100%').justifyContent(FlexAlign.SpaceAround)
- 三种尺寸梯度:80px、120px、160px
- 使用
FlexAlign.SpaceAround 均匀分布
- 相同图片源,不同尺寸展示
2.4 带描述文本
this.SectionTitle('带描述文本')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=500',
imageWidth: 300,
imageHeight: 200,
showCaption: true,
captionText: '美丽的自然风光'
})
showCaption: true 启用描述文本显示
captionText 设置描述内容
- 描述文本自动定位在图片底部
三:填充模式实战
3.1 五种填充模式对比
| 填充模式 | 特点 | 适用场景 | 变形风险 |
|---|
| contain | 完整显示,留白可能 | 产品详情、证件照 | 无 |
| cover | 填满容器,可能裁剪 | 封面图、背景图 | 无 |
| fill | 拉伸填充 | 固定比例设计 | 高 |
| scale-down | 缩小显示 | 小图展示 | 无 |
| none | 原始尺寸 | 精确尺寸需求 | 无 |
3.2 contain - 完整显示模式
this.SectionTitle('contain - 完整显示')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
imageFit: 'contain',
bgColor: '#E8F4FF'
})
- 保持图片完整性,不裁剪
- 自动计算缩放比例,填充到容器
- 使用
bgColor 设置留白区域背景色
RcImage({
imageSrc: productImageUrl,
imageWidth: vp2px(350),
imageHeight: vp2px(350),
imageFit: 'contain',
bgColor: '#FFFFFF',
rcBorderWidth: 1,
rcBorderColor: '#E0E0E0'
})
3.3 cover - 填满裁剪模式 (推荐)
this.SectionTitle('cover - 填满裁剪 (默认)')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
imageFit: 'cover'
})
- 填满整个容器,无留白
- 超出部分自动裁剪
- 默认模式,无需显式设置
RcImage({
imageSrc: newsImageUrl,
imageWidth: 120,
imageHeight: 80,
imageFit: 'cover',
imageShape: 'round',
imageRadius: 8
})
3.4 fill - 拉伸填充模式
this.SectionTitle('fill - 拉伸填充')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
imageFit: 'fill'
})
- 可能导致图片变形
- 适合已知图片比例的场景
- 慎用于用户上传内容
3.5 scale-down - 缩小显示模式
this.SectionTitle('scale-down - 缩小显示')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
imageFit: 'scale-down',
bgColor: '#FFF5E6'
})
- 仅缩小,不放大
- 小图保持原始尺寸
- 大图缩小到容器内
3.6 none - 原始尺寸模式
this.SectionTitle('none - 原始尺寸')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
imageFit: 'none',
bgColor: '#F0F0F0'
})
四:图片形状实战
4.1 三种形状系统对比
| 形状类型 | 参数值 | 圆角处理 | 适用场景 |
|---|
| 方形 | square | 无圆角 | 通用场景 |
| 圆形 | circle | 自动圆角 | 头像、标志 |
| 圆角 | round | 可自定义 | 卡片、缩略图 |
4.2 方形图片 (默认)
this.SectionTitle('方形 (默认)')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500',
imageWidth: 150,
imageHeight: 150,
imageShape: 'square'
})
- 默认形状,无需显式设置
- 直角矩形,无圆角处理
- 最通用的展示形式
4.3 圆形图片
this.SectionTitle('圆形')
Row({ space: 15 }) {
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500', imageWidth: 80, imageHeight: 80, imageShape: 'circle', imageFit: 'cover' })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=500', imageWidth: 100, imageHeight: 100, imageShape: 'circle', imageFit: 'cover' })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1518173946687-a4c8892bbd9f?w=500', imageWidth: 120, imageHeight: 120, imageShape: 'circle', imageFit: 'cover' })
}.width('100%').justifyContent(FlexAlign.SpaceAround)
- 三种尺寸梯度:80px、100px、120px
- 使用
cover 填充模式避免变形
- 均匀分布,视觉平衡
@Builder ChatAvatarList() {
List({ space: 12 }) {
ForEach(this.chatList, (item: ChatItem) => {
ListItem() {
Row({ space: 12 }) {
RcImage({
imageSrc: item.avatarUrl,
imageWidth: 48,
imageHeight: 48,
imageShape: 'circle',
imageFit: 'cover',
rcBorderWidth: 2,
rcBorderColor: '#E0E0E0'
})
Column({ space: 4 }) {
Text(item.name).fontSize(16).fontWeight(FontWeight.Medium)
Text(item.lastMessage).fontSize(14).fontColor('#909399')
}.alignItems(HorizontalAlign.Start)
}.width('100%').padding(12)
}
})
}
}
4.4 圆角图片 (可自定义)
this.SectionTitle('圆角 (可自定义圆角大小)')
Column({ space: 15 }) {
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500', imageWidth: 300, imageHeight: 200, imageShape: 'round', imageRadius: 8, showCaption: true, captionText: '圆角 8' })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=500', imageWidth: 300, imageHeight: 200, imageShape: 'round', imageRadius: 16, showCaption: true, captionText: '圆角 16' })
RcImage({ imageSrc: 'https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=500', imageWidth: 300, imageHeight: 200, imageShape: 'round', imageRadius: 32, showCaption: true, captionText: '圆角 32' })
}
| 圆角值 | 视觉效果 | 适用场景 | 使用频率 |
|---|
| 4-8px | 微圆角 | 小尺寸图片、列表缩略图 | ⭐⭐⭐⭐⭐ |
| 12-16px | 标准圆角 | 卡片图片、内容配图 | ⭐⭐⭐⭐ |
| 20-32px | 大圆角 | 封面图、特色展示 | ⭐⭐⭐ |
| 50% | 完全圆形 | 头像、徽章 | ⭐⭐⭐⭐ |
@Builder ProductCard(product: ProductItem) {
Column({ space: 8 }) {
RcImage({
imageSrc: product.imageUrl,
imageWidth: 180,
imageHeight: 180,
imageShape: 'round',
imageRadius: 12,
imageFit: 'cover',
previewable: true
})
Text(product.name).fontSize(15).fontWeight(FontWeight.Medium).maxLines(2).textOverflow({ overflow: TextOverflow.Ellipsis })
Row({ space: 6 }) {
Text(`¥${product.price}`).fontSize(18).fontColor('#FF4500').fontWeight(FontWeight.Bold)
Text(`¥${product.originalPrice}`).fontSize(14).fontColor('#909399').decoration({ type: TextDecorationType.LineThrough })
}
}.width(180).padding(12).backgroundColor('#FFFFFF').borderRadius(8)
}
五:加载状态实战
5.1 四种加载状态场景
| 状态类型 | 触发条件 | 显示内容 | 用户体验 |
|---|
| 加载中 | 图片未加载完成 | 加载指示器 | 告知用户等待 |
| 加载成功 | 图片加载完成 | 正常图片 | 流畅展示 |
| 加载失败 | 网络错误/地址错误 | 错误占位图 | 避免空白 |
| 隐藏状态 | 关闭状态显示 | 无提示 | 简洁设计 |
5.2 正常加载状态
this.SectionTitle('正常加载')
RcImage({
imageSrc: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=500',
imageWidth: 300,
imageHeight: 200,
showLoading: true,
onImageLoad: () => {
console.log('图片加载成功')
}
})
showLoading: true 显示加载指示器
onImageLoad 回调监听加载成功
- 自动显示旋转动画
@State loadedImages: Set<string> = new Set()
RcImage({
imageSrc: imageUrl,
imageWidth: 200,
imageHeight: 200,
showLoading: !this.loadedImages.has(imageUrl),
onImageLoad: () => {
this.loadedImages.add(imageUrl)
}
})
5.3 加载失败状态
this.SectionTitle('加载失败 (错误地址)')
RcImage({
imageSrc: 'https://invalid-url.com/image.jpg',
imageWidth: 300,
imageHeight: 200,
showError: true,
onImageError: (error: string) => {
console.log('图片加载失败:', error)
}
})
showError: true 显示错误占位图
onImageError 回调接收错误信息
- 自动显示图片错误符号
@State retryCount: number = 0
@State currentImageUrl: string = ''
@Builder ImageWithRetry() {
RcImage({
imageSrc: this.currentImageUrl + `?t=${this.retryCount}`,
imageWidth: 300,
imageHeight: 200,
showError: true,
onImageError: (error: string) => {
if (this.retryCount < 3) {
setTimeout(() => {
this.retryCount++
console.log(`重试加载图片,第 ${this.retryCount} 次`)
}, 2000)
} else {
console.log('达到最大重试次数,停止重试')
}
}
})
}
5.4 自定义占位图样式
this.SectionTitle('自定义占位图颜色')
RcImage({
imageSrc: 'https://invalid-url.com/image2.jpg',
imageWidth: 300,
imageHeight: 200,
showError: true,
placeholderColor: '#f56c6c',
placeholderSize: 60
})
placeholderColor: 占位符颜色 (支持十六进制/RGB)
placeholderSize: 占位符尺寸 (建议 40-80)
const PLACEHOLDER_COLORS = {
primary: '#409EFF',
success: '#67C23A',
warning: '#E6A23C',
danger: '#F56C6C',
info: '#909399'
}
RcImage({
imageSrc: errorImageUrl,
imageWidth: 200,
imageHeight: 200,
showError: true,
placeholderColor: PLACEHOLDER_COLORS.primary,
placeholderSize: 50
})
5.5 隐藏加载状态
this.SectionTitle('隐藏加载状态')
RcImage({
imageSrc: 'https://invalid-url.com/image3.jpg',
imageWidth: 300,
imageHeight: 200,
showLoading: false,
showError: false
})
showLoading: false 隐藏加载指示器
showError: false 隐藏错误占位图
- 适合快速加载或本地图片