HarmonyOS RcList 组件实战：尺寸计算与视觉样式详解

前言

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(),
            : ,
            : ,
            : ,
            : { : , :  },
            : ,
            : { : , : , :  },
            : ,
            : ,
            : 
          })
        }
        ().().().(.).({ : , :  })
      }.().()
    }.().().()
  }
}