HarmonyOS6 半年磨一剑 - RcList 组件核心架构与类型系统设计

文章目录

• 前言
  • 开源计划
  • rchoui 官网
• 一、组件整体架构
  • 1.1 双组件协作模式
  • 1.2 文件结构
  • 1.3 依赖关系图
• 二、类型系统设计
  • 2.1 核心类型总览
  • 2.2 方向类型设计
  • 2.3 缩略图尺寸类型
  • 2.4 角标配置接口
  • 2.5 额外图标配置接口
  • 2.6 列表数据模型
• 三、RcList 容器核心实现
  • 3.1 关键 @Param 属性
  • 3.2 滚动事件三元组
  • 3.3 @BuilderParam 插槽机制
• 四、RcListItem 结构划分
  • 4.1 四区布局模型
  • 4.2 主体内容区渲染
  • 4.3 右侧操作区互斥逻辑
• 总结

前言

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

开源计划

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

rchoui 官网

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

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

一、组件整体架构

1.1 双组件协作模式

RcList 体系采用容器 + 子项的双组件协作模式：

• RcList：列表容器，负责滚动控制、边框、间距、背景色、滚动事件派发
• RcListItem：列表子项，负责单行内容渲染，包含图标、标题、描述、角标、开关、箭头

两者通过 @BuilderParam 插槽机制连接，组合使用时代码结构清晰：

import{ RcList, RcListItem }from'rchoui'RcList(){RcListItem({ rcListItemTitle:'第一项'})RcListItem({ rcListItemTitle:'第二项'})}

这种设计让容器与子项职责分离，容器只管"怎么滚"，子项只管"怎么显示"，彼此不耦合。

1.2 文件结构

rchoui/src/main/ets/dataComponents/RcList/ ├── index.ets # 组件实现（RcList + RcListItem） ├── index.type.ets # 类型定义（Props、Config 接口） └── README.md # API 文档 

组件将类型定义与实现代码完全分离，遵循单一职责原则。类型文件 index.type.ets 可独立引用，方便二次封装。

1.3 依赖关系图

关于RcIcon 在我们之前的章节中已经有所讲解了， 至于该三方库的源码 是否公开，目前还没有想好， 因此这里仅展示了一些设计原则，依赖关系等， 方便开发者在使用时能够更加清晰的理解，为什么这样用，或者 为什么这个ui组件可以通过某种方式来展示等。。

RcList / RcListItem | +-- RcIcon (额外图标渲染) | +-- RcSwitch (开关组件) | +-- RcUIBaseStyle (全局基础样式) | +-- RcGlobalConfig (全局配置) | +-- getSizeByUnit (尺寸工具函数) 

提示：RcIcon 和 RcSwitch 是 rchoui 内置的基础组件，RcList 通过组合而非继承的方式复用它们。

二、类型系统设计

2.1 核心类型总览

index.type.ets 中定义了完整的类型体系，分为联合类型、接口两大类：

2.2 方向类型设计

// RcListDirection：支持水平和垂直两种排列exporttypeRcListDirection='row'|'column'

RcListDirection 同时被 RcList（容器方向）和 RcListItem（子项内部排列）使用，复用同一类型约束，避免冗余。

2.3 缩略图尺寸类型

// 预设三档尺寸，也支持直接传数值exporttypeRcListItemThumbSize='small'|'medium'|'large'// 在组件 @Param 中的声明：@Param rcListItemThumbSize: RcListItemThumbSize | RcStringNumber ='medium'

通过 RcListItemThumbSize | RcStringNumber 联合类型，开发者既可使用语义化字符串（'small'、'medium'、'large'），也可以直接传入自定义数值（如 50），兼顾便捷性和灵活性。

三档预设对应像素值：

2.4 角标配置接口

exportinterfaceRcListBadgeConfig{// 角标内容，支持数字和字符串 value?:string|number// 角标背景色，默认红色 '#fa3534' color?: ResourceColor // 是否显示点状角标（优先级高于 value） isDot?:boolean// 最大值，超过后显示为 '99+'，默认 99 max?:number}

RcListBadgeConfig 的设计充分考虑了真实业务场景：

• 数字角标（未读消息数）
• 超出最大值自动截断（99+）
• 点状角标（仅提示有新内容，不显示数量）
• 文字角标（如 'NEW'、'HOT'）

2.5 额外图标配置接口

exportinterfaceRcListExtraIconConfig{// 支持 RcIcon 图标名，也支持本地/网络图片 name:keyof RcIconDataType | ResourceStr color?: ResourceColor size?: RcStringNumber // 默认 20}

name 字段使用 keyof RcIconDataType | ResourceStr 联合类型，使得：

• 传入 'icon-houi_bell_outline' 等字符串时，使用内置矢量图标
• 传入 $r('app.media.xxx') 或 URL 时，使用图片资源

这是类型引导开发的典型体现，IDE 可以为 keyof RcIconDataType 提供自动补全。

2.6 列表数据模型

exportinterfaceRcListItemData{ id?:string|number title?:string note?:string thumb?: ResourceStr rightText?:string badge?: RcListBadgeConfig extraIcon?: RcListExtraIconConfig disabled?:boolean customData?: Record<string, ESObject>// 自定义扩展数据}

RcListItemData 是为数据驱动渲染预留的数据模型，customData 字段允许携带任意业务数据，具有良好的可扩展性。

三、RcList 容器核心实现

3.1 关键 @Param 属性

@ComponentV2export struct RcList {// 是否显示外层边框@Param rcListBorder:boolean=false// 列表高度（为 0 且 rcListScrollable 为 true 时不启用滚动）@Param rcListHeight: RcStringNumber =0// 是否启用滚动（需要配合 rcListHeight 使用）@Param rcListScrollable:boolean=true// 滚动条状态@Param rcListScrollBarState: BarState = BarState.Auto // 边缘弹性效果@Param rcListEdgeEffect: EdgeEffect = EdgeEffect.Spring // 外部注入的滚动控制器@Param rcListScroller: Scroller =newScroller()// 内容插槽@BuilderParamrcListContentBuilder:()=>void=this.rcListDefaultContent }

提示：rcListHeight 和 rcListScrollable 需要同时满足才会渲染可滚动容器。这是一种防误用的设计——避免开发者忘记设置高度导致滚动失效。

3.2 滚动事件三元组

RcList 对外暴露三个滚动相关事件：

// 实时滚动偏移量（每帧触发）@EventonRcListScroll:(scrollOffset:number, scrollState: ScrollState)=>void=()=>{}// 滚动到底部（加载更多的触发点）@EventonRcListScrollToLower:()=>void=()=>{}// 滚动到顶部（下拉刷新的触发点）@EventonRcListScrollToUpper:()=>void=()=>{}

内部通过 handleRcListScroll 和 handleRcListScrollEdge 两个方法处理 ArkUI Scroll 组件的原生事件，并转化为更语义化的上层事件。

3.3 @BuilderParam 插槽机制

// 内容插槽声明@BuilderParamrcListContentBuilder:()=>void=this.rcListDefaultContent // 默认空实现@BuilderrcListDefaultContent(){}

使用方通过尾随闭包语法填充列表内容：

RcList({ rcListBorder:true}){// 这里的内容会被注入到 rcListContentBuilder 中RcListItem({ rcListItemTitle:'设置项 A'})RcListItem({ rcListItemTitle:'设置项 B'})}

这是 ArkUI @BuilderParam 的标准用法，等效于 Web 开发中的 slot 插槽机制。

四、RcListItem 结构划分

4.1 四区布局模型

每个 RcListItem 的水平布局分为四个区域：

|---额外图标区---|---缩略图区---|---主体内容区（flex:1）---|---右侧操作区---| 

对应四个 @Builder 方法：

@BuilderrenderRcListItemExtraIcon()// 左侧图标（extraIcon）@BuilderrenderRcListItemThumb()// 左侧缩略图（thumb + badge）@BuilderrenderRcListItemBody()// 中间标题 + 描述@BuilderrenderRcListItemFooter()// 右侧文字/开关/箭头

主体内容区使用 .layoutWeight(1) 占据剩余空间，左右两侧区域按内容自适应宽度。

4.2 主体内容区渲染

@BuilderrenderRcListItemBody(){Column({ space:4}){if(this.rcListItemTitle){Text(this.rcListItemTitle).fontSize(15)// 禁用时文字变灰.fontColor(this.rcListItemDisabled ?'#c0c4cc':'#303133').fontWeight(FontWeight.Medium)}if(this.rcListItemNote){Text(this.rcListItemNote).fontSize(13).fontColor('#909399')// 限制行数与省略号：rcListItemEllipsis 为 1-5 时生效.maxLines(this.rcListItemEllipsis >0&&this.rcListItemEllipsis <=5?this.rcListItemEllipsis :undefined).textOverflow(this.rcListItemEllipsis >0?{ overflow: TextOverflow.Ellipsis }:undefined)}}.alignItems(HorizontalAlign.Start).layoutWeight(1)}

描述文本的 maxLines 和 textOverflow 联动控制，rcListItemEllipsis 取值范围限定在 1-5，超出范围则不限制行数，这是一种防御性参数校验。

4.3 右侧操作区互斥逻辑

@BuilderrenderRcListItemFooter(){Row({ space:8}){// 右侧文字（可与开关/箭头共存）if(this.rcListItemRightText){Text(this.rcListItemRightText).fontSize(14).fontColor('#909399')}if(this.rcListItemShowSwitch){// 优先显示开关RcSwitch({...})}elseif(this.rcListItemShowArrow &&!this.rcListItemShowSwitch){// 没有开关时才显示箭头RcIcon({ name:'icon-houi_chevron_right_outline', iconSize:16, color:'#c0c4cc'})}}}

开关与箭头互斥是业务逻辑的体现：有开关的项目不需要箭头引导跳转。条件判断层次清晰，避免了两者同时显示的 UI 冲突。

总结

RcList 与 RcListItem 构成的双组件体系，是 HarmonyOS6 ArkUI 场景下列表开发的高效解法。其核心设计理念包括：类型驱动开发（完整的 TypeScript 类型约束）、职责分离（容器与子项解耦）、全局主题集成（AppStorageV2 响应式配置）以及渲染分支策略（滚动与静态的智能切换）。

掌握了本篇的架构原理，你已经对整个组件体系有了扎实的底层认知，后续深入缩略图、角标、交互、实战等专题时将会更加游刃有余。

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