HarmonyOS6 RcList 组件核心架构与类型系统设计

2.1 方向与尺寸设计

RcListDirection 同时被容器和子项使用，支持水平和垂直两种排列，复用同一类型约束避免冗余：

export type RcListDirection = 'row' | 'column'

缩略图尺寸支持语义化字符串或自定义数值，兼顾便捷性和灵活性：

// 预设三档尺寸，也支持直接传数值
export type RcListItemThumbSize = 'small' | 'medium' | 'large'

// 在组件 @Param 中的声明
@Param rcListItemThumbSize: RcListItemThumbSize | RcStringNumber = 'medium'

三档预设对应像素值如下：

2.2 配置接口设计

角标配置充分考虑了真实业务场景，支持数字截断、点状提示及文字标签：

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

额外图标配置利用联合类型实现类型引导，IDE 可为内置图标名提供自动补全：

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

2.3 数据模型

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

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

三、RcList 容器核心实现

3.1 关键 @Param 属性

容器的核心属性集中在滚动控制和外观定制上。注意 rcListHeight 和 rcListScrollable 需要同时满足才会渲染可滚动容器，这是一种防误用的设计——避免开发者忘记设置高度导致滚动失效。

@ComponentV2
export 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 = new Scroller()
  // 内容插槽
  @BuilderParam rcListContentBuilder: () => void = this.rcListDefaultContent
}

3.2 滚动事件三元组

RcList 对外暴露三个滚动相关事件，内部通过处理 ArkUI Scroll 组件的原生事件，转化为更语义化的上层事件：

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

3.3 @BuilderParam 插槽机制

使用方通过尾随闭包语法填充列表内容，这是 ArkUI @BuilderParam 的标准用法，等效于 Web 开发中的 slot 插槽机制：

// 内容插槽声明
@BuilderParam rcListContentBuilder: () => void = this.rcListDefaultContent

// 默认空实现
@Builder rcListDefaultContent() {}

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

四、RcListItem 结构划分

4.1 四区布局模型

每个 RcListItem 的水平布局分为四个区域，主体内容区使用 .layoutWeight(1) 占据剩余空间，左右两侧区域按内容自适应宽度：

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

对应四个 @Builder 方法：

@Builder renderRcListItemExtraIcon() // 左侧图标（extraIcon）
@Builder renderRcListItemThumb()     // 左侧缩略图（thumb + badge）
@Builder renderRcListItemBody()      // 中间标题 + 描述
@Builder renderRcListItemFooter()    // 右侧文字/开关/箭头

4.2 主体内容区渲染

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

@Builder renderRcListItemBody() {
  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)
}

4.3 右侧操作区互斥逻辑

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

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

总结

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