前言
RcList 是 HarmonyOS 生态中一个功能丰富的列表组件,支持缩略图、角标及额外图标等多种视觉元素的组合。本文将深入讲解其核心机制,包括尺寸单位转换、禁用状态处理以及完整的实战配置方案。
尺寸计算与工具函数
getSizeByUnit 的作用
getSizeByUnit 工具函数用于将 RcStringNumber(string | number)统一转换为 ArkUI 组件属性可接受的值。这使得 rcListWidth、rcListHeight、rcListSpace 等属性既可以传数字(单位为 vp),也可以传百分比字符串。
// utils.ts 简化示意
export function getSizeByUnit(size: string | number): string | number {
if (typeof size === 'number') {
return size; // 数字直接返回(单位为 vp)
}
return size; // 字符串直接返回(支持 '100%'、'50vp' 等)
}
不透明度与禁用状态
在 RcListItem 的构建逻辑中,通过全局 opacity 实现禁用效果比逐一修改子元素颜色更高效。当 rcListItemDisabled 为真时,整个列表项(包括缩略图、图标、文字)统一降低到 60% 透明度,视觉上保持一致地传达'不可用'状态。
// RcListItem build() 中的禁用视觉处理
.opacity(this.rcListItemDisabled ? 0.6 : 1)
完整实战示例
以下是一个综合展示缩略图、角标、额外图标三套系统的完整可运行页面。代码中包含了不同尺寸的缩略图配置、多种角标形态(数字、超限截断、点状、文字)以及矢量与本地图片两种额外图标模式。

import { RcList, }
struct {
() {
() {
({ : }) {
().().(.).({ : , : })
().().().({ : })
({ : }) {
({
: ,
: ,
: $r(),
: ,
: ,
:
})
({
: ,
: ,
: $r(),
: ,
: ,
:
})
({
: ,
: ,
: $r(),
: ,
: ,
: ,
:
})
}
().().().({ : })
({ : }) {
({
: ,
: ,
: $r(),
: ,
: ,
: { : },
:
})
({
: ,
: ,
: $r(),
: ,
: ,
: { : , : },
:
})
({
: ,
: ,
: $r(),
: ,
: ,
: { : , : },
:
})
({
: ,
: ,
: $r(),
: ,
: ,
: { : , : },
: ,
:
})
}
().().().({ : })
({ : }) {
({
: ,
: ,
: ,
: { : , : , : },
:
})
({
: ,
: ,
: ,
: { : , : , : },
:
})
({
: ,
: ,
: ,
: { : , : , : },
: ,
:
})
}
().().().({ : })
({ : }) {
({
: ,
: ,
: ,
: { : $r(), : },
: ,
:
})
}
().().().({ : })
({ : }) {
({
: ,
: ,
: $r(),
: ,
: ,
: ,
: { : , : },
: ,
: { : , : , : },
: ,
: ,
:
})
}
().().().(.).({ : , : })
}.().()
}.().().()
}
}


