HarmonyOS RcList 组件缩略图、角标与图标系统设计

提示：要获得完美正圆效果，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 })
} else if (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 数字截断逻辑

private getRcListItemBadgeText(): string {
  if (!this.rcListItemBadge.value) return ''
  const max = this.rcListItemBadge.max || 99
  const value = this.rcListItemBadge.value
  if (typeof value === 'number' && value > max) {
    return `${max}+`
  }
  return String(value)
}

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

2.4 角标颜色处理

private getRcListItemBadgeColor(): string | Color {
  const color = this.rcListItemBadge.color
  if (!color) return '#fa3534'
  if (typeof color === 'string') return color
  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），适合设置页、功能菜单
• 缩略图：使用图片，适合头像、商品封面等内容型列表

@Builder renderRcListItemExtraIcon() {
  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，因此支持两种图标来源： 模式一：内置矢量图标

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()
    this.renderRcListItemThumb()
    this.renderRcListItemBody()
    this.renderRcListItemFooter()
  }
}

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, rcListItemBadge: { value: 5 } })

总结

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

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