HarmonyOS6 半年磨一剑 - RcList 组件综合示例与尺寸计算

文章目录

• 前言
  • 开源计划
  • rchoui 官网
• 一、尺寸计算与工具函数
  • 1.1 getSizeByUnit 的作用
  • 1.2 不透明度与禁用状态
• 二、完整实战示例
• 三、视觉样式对照表
  • 3.1 缩略图参数速查
  • 3.2 角标参数速查
  • 3.3 额外图标参数速查
• 总结

前言

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 缩略图参数速查

3.2 角标参数速查

3.3 额外图标参数速查

总结

RcList 的视觉富化系统由缩略图、角标、额外图标三个子系统有机组合而成。缩略图通过 Stack 叠加实现了角标依附效果，额外图标通过类型联合支持矢量与图片双模式，角标通过智能截断和多形态适配了真实业务场景。三套系统可以独立使用，也可以自由组合，灵活性极强。

在实际开发中，建议遵循以下原则：内容型列表（头像、商品）使用缩略图，功能型列表（设置、菜单）使用额外图标，消息提示场景搭配角标系统，将视觉信息层次做到最优。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是我持续创作的动力！