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

一、缩略图系统设计

1.1 缩略图渲染流程

RcListItem 的缩略图由 renderRcListItemThumb() 负责渲染，该方法使用 Stack 容器将图片和角标叠加在一起：

@Builder
renderRcListItemThumb() {
  if (this.rcListItemThumb) {
    Stack() {
      // 底层：图片本体
      Image(this.rcListItemThumb)
        .width(this.getRcListItemThumbSize())
        .height(this.getRcListItemThumbSize())
        .borderRadius(getSizeByUnit(this.rcListItemThumbRadius))
        .objectFit(ImageFit.Cover)
      // 上层：角标（条件渲染）
      if (this.rcListItemShowBadge && this.rcListItemBadge) {
        // ... 角标渲染逻辑
      }
    }
      .alignContent(Alignment.TopEnd) // 角标对齐右上角
      .margin({ right: 12 })
  }
}

设计要点：

• 图片使用 ImageFit.Cover 填充模式，确保任何尺寸的图片都不会被拉伸变形
• Stack.alignContent(Alignment.TopEnd) 将角标定位在右上角
• margin({ right: 12 }) 与主体内容保持间距

1.2 尺寸映射方法

private getRcListItemThumbSize(): number {
  // 直接传数字：原样返回
  if (typeof this.rcListItemThumbSize === 'number') {
    return this.rcListItemThumbSize
  }
  // 传数字字符串（如 '50'）：转换为数字
  if (typeof this.rcListItemThumbSize === 'string' && !isNaN(Number(this.rcListItemThumbSize))) {
    return Number(this.rcListItemThumbSize)
  }
  // 预设枚举值
  switch (this.rcListItemThumbSize) {
    case 'small': return 40
    case 'large': return 80
    case 'medium': default: return 60
  }
}

这个方法的处理顺序体现了输入容错原则：先处理精确类型（number），再处理可转换类型（数字字符串），最后处理语义预设值。无论用户怎么传参，都不会报错。

1.3 缩略图三档尺寸对比

预设值	尺寸	典型场景
'small'	40 × 40	小图标、应用图标
'medium'	60 × 60	联系人头像、商品封面
'large'	80 × 80	专辑封面、大头像
自定义数字	N × N	精准控制尺寸场景

1.4 圆角控制

rcListItemThumbRadius 参数控制缩略图圆角，配合尺寸可以实现多种形态：

// 轻微圆角（卡片风格）
RcListItem({ 
  rcListItemThumb: $r('app.media.startIcon'), 
  rcListItemThumbSize: 'medium', 
  rcListItemThumbRadius: 8 
})
// 正圆头像（半径 = 尺寸 / 2）
RcListItem({ 
  rcListItemThumb: $r('app.media.startIcon'), 
  rcListItemThumbSize: 60, 
  rcListItemThumbRadius: 30 // 60 / 2 = 30，形成正圆 
})
// 无圆角（方形图标）
RcListItem({ 
  rcListItemThumb: $r('app.media.startIcon'), 
  rcListItemThumbSize: 'medium', 
  rcListItemThumbRadius: 0 
})

提示：要获得完美正圆效果，rcListItemThumbRadius 需要等于 rcListItemThumbSize 的一半。当 rcListItemThumbSize 使用预设值时，圆角对应关系为：small → 20，medium → 30，large → 40。

---

二、角标系统实现

2.1 角标三种形态

RcListBadgeConfig 支持三种角标形态，通过 isDot、value 组合控制：

配置组合	渲染形态	典型场景
{ isDot: true }	红点（8px 圆形）	仅提示有新内容
{ value: 5 }	数字气泡	未读消息数量
{ value: 'NEW' }	文字气泡	新功能标签

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 // 未设置 max 时默认 99
  const value = this.rcListItemBadge.value // 只对数字进行截断
  if (typeof value === 'number' && value > max) {
    return `${max}+` // 超出则显示 "99+"
  }
  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 // 字符串颜色直接使用
  }
  // Resource 类型（$r() 引用）暂不支持直接渲染，回退到默认红色
  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，因此支持两种图标来源：

模式一：内置矢量图标

// 使用 rchoui 内置的矢量图标（字体图标）
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 常用图标与颜色搭配

场景	图标名	推荐颜色
通知/消息	icon-houi_bell_outline	#409eff（蓝色）
设置	icon-houi_settings_outline	#909399（灰色）
下载	icon-houi_download_outline	#67c23a（绿色）
夜间模式	icon-houi_moon_outline	#303133（深色）
首页	icon-houi_home_outline	#e6a23c（橙色）
星标/收藏	icon-houi_star_outline	#e6a23c（橙色）
消息	icon-houi_message_circle_outline	#409eff（蓝色）
同步	icon-houi_sync_outline	#67c23a（绿色）
锁定	icon-houi_lock_outline	#c0c4cc（浅灰）

---

四、三系统组合布局

4.1 布局优先级

当同时设置了额外图标和缩略图时，两者都会渲染，布局从左到右依次为：

| extraIcon | thumb | 标题 + 描述 | rightText / switch / arrow | 

实际代码中的渲染顺序：

build() {
  Row({ space: 0 }) {
    this.renderRcListItemExtraIcon() // 1. 额外图标（最左侧）
    this.renderRcListItemThumb() // 2. 缩略图（extra 右侧）
    this.renderRcListItemBody() // 3. 标题 + 描述（flex:1）
    this.renderRcListItemFooter() // 4. 右侧操作区
  }
}

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, // 此设置无效，因为没有 thumb 
  rcListItemBadge: { value: 5 } 
})

总结

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

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