HarmonyOS6 半年磨一剑 - RcList 组件缩略图、角标与图标系统

文章目录

• 前言
  • 开源计划
  • rchoui 官网
• 一、缩略图系统设计
  • 1.1 缩略图渲染流程
  • 1.2 尺寸映射方法
  • 1.3 缩略图三档尺寸对比
  • 1.4 圆角控制
• 二、角标系统实现
  • 2.1 角标三种形态
  • 2.2 角标渲染分支
  • 2.3 数字截断逻辑
  • 2.4 角标颜色处理
  • 2.5 四种角标配置示例
• 三、额外图标系统
  • 3.1 额外图标的定位
  • 3.2 双模式图标支持
  • 3.3 常用图标与颜色搭配
• 四、三系统组合布局
  • 4.1 布局优先级
  • 4.2 角标依附于缩略图
• 总结

前言

Hello 各位开发者们大家好， 我是若城，今天我们开始对Rchoui三方库新的组件开始讲解， 本期我们主要讲解的是 RcList 这个组件， 话不多说我们先看下效果图吧~~~

开源计划

项目预计于 2026 年 7 月中旬正式开源，届时可通过三方库直接下载使用。在此期间，我会通过系列文章逐一介绍每个模块的设计思路与实现细节。

rchoui 官网

目前暂定 rchoui 官网地址：http://rchoui.ruocheng.site/

需要注意的是，当前官网还在完善当中，会在后续更新中逐步完善，届时可以为大家提供更加完善的说明文档。

一、缩略图系统设计

1.1 缩略图渲染流程

RcListItem 的缩略图由 renderRcListItemThumb() 负责渲染，该方法使用 Stack 容器将图片和角标叠加在一起：

@BuilderrenderRcListItemThumb(){if(this.rcListItemThumb){Stack(){// 底层：图片本体Image(this.rcListItemThumb).width(this.getRcListItemThumbSize()).height(this.getRcListItemThumbSize()).borderRadius(getSizeByUnit(this.rcListItemThumbRadius)).objectFit(ImageFit.Cover)// 上层：角标（条件渲染）if(this.rcListItemShowBadge &&this.rcListItemBadge){// ... 角标渲染逻辑}}.alignContent(Alignment.TopEnd)// 角标对齐右上角.margin({ right:12})}}

设计要点：

• 图片使用 ImageFit.Cover 填充模式，确保任何尺寸的图片都不会被拉伸变形
• Stack.alignContent(Alignment.TopEnd) 将角标定位在右上角
• margin({ right: 12 }) 与主体内容保持间距

1.2 尺寸映射方法

privategetRcListItemThumbSize():number{// 直接传数字：原样返回if(typeofthis.rcListItemThumbSize ==='number'){returnthis.rcListItemThumbSize }// 传数字字符串（如 '50'）：转换为数字if(typeofthis.rcListItemThumbSize ==='string'&&!isNaN(Number(this.rcListItemThumbSize))){returnNumber(this.rcListItemThumbSize)}// 预设枚举值switch(this.rcListItemThumbSize){case'small':return40case'large':return80case'medium':default:return60}}

这个方法的处理顺序体现了输入容错原则：先处理精确类型（number），再处理可转换类型（数字字符串），最后处理语义预设值。无论用户怎么传参，都不会报错。

1.3 缩略图三档尺寸对比

1.4 圆角控制

rcListItemThumbRadius 参数控制缩略图圆角，配合尺寸可以实现多种形态：

// 轻微圆角（卡片风格）RcListItem({ rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemThumbRadius:8})// 正圆头像（半径 = 尺寸 / 2）RcListItem({ rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:60, rcListItemThumbRadius:30// 60 / 2 = 30，形成正圆})// 无圆角（方形图标）RcListItem({ rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemThumbRadius:0})

提示：要获得完美正圆效果，rcListItemThumbRadius 需要等于 rcListItemThumbSize 的一半。当 rcListItemThumbSize 使用预设值时，圆角对应关系为：small → 20，medium → 30，large → 40。

二、角标系统实现

2.1 角标三种形态

RcListBadgeConfig 支持三种角标形态，通过 isDot、value 组合控制：

2.2 角标渲染分支

// 在 Stack 中叠加渲染角标if(this.rcListItemBadge.isDot){// 点状角标：固定 8px 红点Circle().width(8).height(8).fill(this.getRcListItemBadgeColor()).position({ x:'100%', y:0}).translate({ x:-4, y:4})// 向左移动半径，向下移动，使圆心在右上角}elseif(this.getRcListItemBadgeText()){// 数字/文字角标Text(this.getRcListItemBadgeText()).fontSize(10).fontColor(Color.White).backgroundColor(this.getRcListItemBadgeColor()).padding({ left:4, right:4, top:2, bottom:2}).borderRadius(10)// 药丸形状.position({ x:'100%', y:0}).translate({ x:-6, y:6})// 右上角偏移定位}

位置计算使用 position({ x: '100%', y: 0 }) 相对于 Stack 的右上角定位，再通过 translate 微调，确保角标压在图片的边缘而非完全超出。

2.3 数字截断逻辑

privategetRcListItemBadgeText():string{if(!this.rcListItemBadge.value){return''}const max =this.rcListItemBadge.max ||99// 未设置 max 时默认 99const value =this.rcListItemBadge.value // 只对数字进行截断if(typeof value ==='number'&& value > max){return`${max}+`// 超出则显示 "99+"}returnString(value)// 数字转字符串，字符串原样返回}

这个方法只对数字类型做截断判断，字符串角标（如 'NEW'）不受 max 影响，设计简洁合理。

2.4 角标颜色处理

privategetRcListItemBadgeColor():string| Color {const color =this.rcListItemBadge.color if(!color){return'#fa3534'// 未配置时默认红色}if(typeof color ==='string'){return color // 字符串颜色直接使用}// Resource 类型（$r() 引用）暂不支持直接渲染，回退到默认红色return'#fa3534'}

颜色处理方法考虑了 ResourceColor 的三种子类型：未定义、字符串、Resource 引用。对于 Resource 类型目前回退到默认色，保证了安全性。

2.5 四种角标配置示例

// 1. 普通数字角标 rcListItemBadge:{ value:5}// 2. 超出最大值角标（显示 99+） rcListItemBadge:{ value:150, max:99}// 3. 点状角标（蓝色） rcListItemBadge:{ isDot:true, color:'#409eff'}// 4. 自定义文字 + 自定义颜色 rcListItemBadge:{ value:'HOT', color:'#ff6700'}

三、额外图标系统

3.1 额外图标的定位

renderRcListItemExtraIcon() 渲染在 RcListItem 的最左侧，位于缩略图的左边。实际使用时，额外图标和缩略图通常二选一：

• 额外图标：使用矢量图标（RcIcon），适合设置页、功能菜单
• 缩略图：使用图片，适合头像、商品封面等内容型列表

@BuilderrenderRcListItemExtraIcon(){if(this.rcListItemShowExtraIcon &&this.rcListItemExtraIcon.name){RcIcon({ name:this.rcListItemExtraIcon.name, iconSize:this.rcListItemExtraIcon.size ||20,// 未指定颜色时回退到全局主题色 color:this.rcListItemExtraIcon.color ||this.baseStyle.primary }).margin({ right:12})}}

3.2 双模式图标支持

RcListExtraIconConfig.name 字段的类型是 keyof RcIconDataType | ResourceStr，因此支持两种图标来源：

模式一：内置矢量图标

// 使用 rchoui 内置的矢量图标（字体图标）RcListItem({ rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_bell_outline',// 内置图标名称 color:'#409eff', size:22}})

模式二：本地或网络图片

// 使用本地 Resource 图片RcListItem({ rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:$r('app.media.startIcon'),// 本地资源 size:24}})// 使用网络图片RcListItem({ rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'https://example.com/icon.png', size:24}})

提示：使用本地 Resource 图片（$r()）作为额外图标时，color 属性无法改变图片颜色，该参数仅对矢量字体图标有效。

3.3 常用图标与颜色搭配

四、三系统组合布局

4.1 布局优先级

当同时设置了额外图标和缩略图时，两者都会渲染，布局从左到右依次为：

| extraIcon | thumb | 标题+描述 | rightText / switch / arrow | 

实际代码中的渲染顺序：

build(){Row({ space:0}){this.renderRcListItemExtraIcon()// 1. 额外图标（最左侧）this.renderRcListItemThumb()// 2. 缩略图（extra 右侧）this.renderRcListItemBody()// 3. 标题+描述（flex:1）this.renderRcListItemFooter()// 4. 右侧操作区}}

4.2 角标依附于缩略图

角标是缩略图的叠加层，不是独立区域。因此：

• 只有设置了 rcListItemThumb 时，角标才会显示
• 若只有额外图标而没有缩略图，角标不会出现在额外图标上

// 正确：角标会显示在缩略图右上角RcListItem({ rcListItemThumb:$r('app.media.startIcon'), rcListItemThumbSize:'medium', rcListItemShowBadge:true, rcListItemBadge:{ value:5}})// 注意：没有设置 thumb，角标不会渲染RcListItem({ rcListItemShowExtraIcon:true, rcListItemExtraIcon:{ name:'icon-houi_bell_outline'}, rcListItemShowBadge:true,// 此设置无效，因为没有 thumb rcListItemBadge:{ value:5}})

总结

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

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

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