HarmonyOS6 半年磨一剑 - RcList 组件综合示例与尺寸计算
文章目录
前言
Hello 各位开发者们大家好， 我是若城，今天我们开始对Rchoui三方库新的组件开始讲解， 本期我们主要讲解的是 RcList 这个组件， 话不多说我们先看下效果图吧~~~
开源计划
项目预计于 2026 年 7 月中旬正式开源，届时可通过三方库直接下载使用。在此期间，我会通过系列文章逐一介绍每个模块的设计思路与实现细节。
rchoui 官网
目前暂定 rchoui 官网地址：http://rchoui.ruocheng.site/
需要注意的是，当前官网还在完善当中，会在后续更新中逐步完善，届时可以为大家提供更加完善的说明文档。
一、尺寸计算与工具函数
1.1 getSizeByUnit 的作用
getSizeByUnit 将 RcStringNumber（string | number）统一转换为 ArkUI 组件属性可接受的值：
// 来自 utils.ts（简化示意）exportfunctiongetSizeByUnit(size:string|number):string|number{if(typeof size ==='number'){return size // 数字直接返回（单位为 vp）}return size // 字符串直接返回（支持 '100%'、'50vp' 等）}这让 rcListWidth、rcListHeight、rcListSpace 等属性既可以传 100（数字 vp）也可以传 '100%'（百分比字符串）。
1.2 不透明度与禁用状态
// RcListItem build() 中的禁用视觉.opacity(this.rcListItemDisabled ?0.6:1)使用全局 opacity 实现禁用效果比逐一修改子元素颜色更高效，整个列表项（包括缩略图、图标、文字）统一降低到 60% 透明度，视觉上一致地传达"不可用"状态。
二、完整实战示例
以下是一个综合展示缩略图、角标、额外图标三套系统的完整可运行页面：
import{ RcList, RcListItem }from'rchoui'@Entry@ComponentV2 struct RcListVisualSystemDemo {build(){Scroll(){Column({ space:20}){Text('视觉富化系统演示').fontSize(22).fontWeight(FontWeight.Bold).margin({ top:20, bottom:8})// ========== 缩略图系统 ==========Text('缩略图尺寸与圆角').fontSize(16).fontColor('#303133').margin({ bottom:4})RcList({ rcListBorder:true}){RcListItem({ rcListItemTitle:'小尺寸 40x40', rcListItemNote:'方形圆角，适合应用图标', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'small', rcListItemThumbRadius:8, rcListItemClickable:true})RcListItem({ rcListItemTitle:'中尺寸 60x60', rcListItemNote:'适中圆角，联系人头像', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemThumbRadius:12, rcListItemClickable:true})RcListItem({ rcListItemTitle:'大尺寸 + 正圆', rcListItemNote:'半径等于尺寸一半，形成正圆', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:80, rcListItemThumbRadius:40, rcListItemClickable:true, rcListItemShowBorder:false})}// ========== 角标系统 ==========Text('角标系统三种形态').fontSize(16).fontColor('#303133').margin({ bottom:4})RcList({ rcListBorder:true}){RcListItem({ rcListItemTitle:'数字角标', rcListItemNote:'显示未读消息数量', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemShowBadge:true, rcListItemBadge:{ value:8}, rcListItemClickable:true})RcListItem({ rcListItemTitle:'超限截断', rcListItemNote:'超过 99 显示为 99+', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemShowBadge:true, rcListItemBadge:{ value:150, max:99}, rcListItemClickable:true})RcListItem({ rcListItemTitle:'点状角标', rcListItemNote:'仅提示有新内容', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemShowBadge:true, rcListItemBadge:{ isDot:true, color:'#fa3534'}, rcListItemClickable:true})RcListItem({ rcListItemTitle:'文字角标', rcListItemNote:'自定义颜色蓝色', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemShowBadge:true, rcListItemBadge:{ value:'NEW', color:'#409eff'}, rcListItemClickable:true, rcListItemShowBorder:false})}// ========== 额外图标系统 ==========Text('额外图标（矢量图标）').fontSize(16).fontColor('#303133').margin({ bottom:4})RcList({ rcListBorder:true}){RcListItem({ rcListItemTitle:'消息通知', rcListItemNote:'蓝色图标', rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_bell_outline', color:'#409eff', size:22}, rcListItemClickable:true})RcListItem({ rcListItemTitle:'下载管理', rcListItemNote:'绿色图标', rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_download_outline', color:'#67c23a', size:22}, rcListItemClickable:true})RcListItem({ rcListItemTitle:'应用设置', rcListItemNote:'灰色图标', rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_settings_outline', color:'#909399', size:22}, rcListItemClickable:true, rcListItemShowBorder:false})}// ========== 本地图片图标 ==========Text('额外图标（本地图片）').fontSize(16).fontColor('#303133').margin({ bottom:4})RcList({ rcListBorder:true}){RcListItem({ rcListItemTitle:'本地图片图标', rcListItemNote:'通过 $r() 引用', rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:$r('app.media.startIcon'), size:24}, rcListItemClickable:true, rcListItemShowBorder:false})}// ========== 三系统综合使用 ==========Text('综合：图标 + 缩略图 + 角标').fontSize(16).fontColor('#303133').margin({ bottom:4})RcList({ rcListBorder:true}){RcListItem({ rcListItemTitle:'消息中心', rcListItemNote:'图标 + 缩略图 + 数字角标', rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemThumbRadius:8, rcListItemShowBadge:true, rcListItemBadge:{ value:3, color:'#fa3534'}, rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_message_circle_outline', color:'#409eff', size:20}, rcListItemRightText:'查看全部', rcListItemClickable:true, rcListItemShowBorder:false})}Text('以上展示了三套视觉系统的全部形态').fontSize(13).fontColor('#909399').textAlign(TextAlign.Center).margin({ top:16, bottom:30})}.width('100%').padding(16)}.width('100%').height('100%').backgroundColor('#f5f5f5')}}三、视觉样式对照表
3.1 缩略图参数速查
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
rcListItemThumb | ResourceStr | '' | 图片资源（本地/网络/base64） |
rcListItemThumbSize | 'small' / 'medium' / 'large' / number | 'medium' | 尺寸 |
rcListItemThumbRadius | RcStringNumber | 4 | 圆角半径 |
3.2 角标参数速查
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
rcListItemShowBadge | boolean | false | 是否显示角标 |
rcListItemBadge.value | string / number | - | 角标内容 |
rcListItemBadge.isDot | boolean | false | 是否点状角标 |
rcListItemBadge.color | ResourceColor | '#fa3534' | 角标颜色 |
rcListItemBadge.max | number | 99 | 最大值（超出显示 N+） |
3.3 额外图标参数速查
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
rcListItemShowExtraIcon | boolean | false | 是否显示额外图标 |
rcListItemExtraIcon.name | string / ResourceStr | - | 图标名或图片资源 |
rcListItemExtraIcon.color | ResourceColor | 主题色 | 图标颜色（仅矢量图标有效） |
rcListItemExtraIcon.size | RcStringNumber | 20 | 图标尺寸 |
总结
RcList 的视觉富化系统由缩略图、角标、额外图标三个子系统有机组合而成。缩略图通过 Stack 叠加实现了角标依附效果，额外图标通过类型联合支持矢量与图片双模式，角标通过智能截断和多形态适配了真实业务场景。三套系统可以独立使用，也可以自由组合，灵活性极强。
在实际开发中，建议遵循以下原则：内容型列表（头像、商品）使用缩略图，功能型列表（设置、菜单）使用额外图标，消息提示场景搭配角标系统，将视觉信息层次做到最优。
如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！
