前言

头像上的角标，是很多社交和协作产品里最有辨识度的细节之一。未读消息、在线状态、身份标签，都可以挂在这里。这个案例虽然不大，但非常贴近真实产品。 这一页适合慢一点读，不是因为代码特别难，而是因为它里面很多决定都和真实页面很像。把这些决定看懂，比把组件名字记住更值钱。

如果把这页当成练习材料，我会优先看它怎样围绕 Badge 挂载在头像上的消息与在线状态 组织页面。因为这一层想清楚了，后面的代码基本就不会散。

这类写法尤其适合落在 IM、社交、团队协作、成员管理页面 这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

别急着抄，先认结构

这一类页面看源码最怕的就是“每一段都认识，但拼起来不知道为什么这么摆”。所以这里先从页面骨架讲起，比直接盯属性更省时间。

页面区域	主要职责	在代码里的典型表现
头部说明区	交代当前案例在演示什么	Text 标题、补充说明、标签文案
核心展示区	承载组件能力的主要效果	Column、Row、业务组件本体
辅助信息区	补充状态、标签、分组或统计信息	次级文本、角标、分组标题、描述块
交互入口区	负责切换、返回、定位、选择等动作	点击事件、按钮、索引条、导航入口

页面里额外定义的数据模型包括：BadgeOnAvatarStatusItem。如果后面准备接接口，我更建议把这些类型继续收口成更直白的业务命名。

这个案例表面看是界面效果，真正该盯的是状态怎么流动，因为大多数可复用价值都藏在这里。

头像徽章要同时表达“是谁”和“现在什么状态”

这页的 isShow 只是外层展示开关，真正有价值的是头像数据里的 avatar、name、badge、dot、color。它们组合在一起，决定用户看到的是未读消息、在线状态，还是某种身份/状态提示。

我会按这三层来读：

• 身份识别：avatar 和 name 让用户先知道这个头像对应谁。
• 提醒强度：badge 大于 0 时表达未读数量，适合消息压力比较明确的场景。
• 状态表达：dot 为 true 时不显示数字，而是用颜色点表达在线、忙碌或特殊身份。

头像上的 Badge 比普通图标角标更敏感，因为它离“人”很近。数字、颜色、大小都不能乱用，否则很容易把在线状态、未读消息和身份标记混在一起。

时间不多的话，先盯这几个入口

我一般不会把所有方法从上到下读一遍，而是先找“用户动一下之后，页面为什么会变”的那条链路。

• 这个案例没有太多额外方法，核心价值主要集中在页面结构和组件组合方式。

我自己读这类方法时，通常只抓一条线：谁触发、谁被改、页面哪里立刻有反馈。把这三件事连起来，很多交互代码一下就顺了。

第一段关键代码：页面是怎么被带起来的

这一段建议慢一点看。它通常决定了页面初始状态，也决定了后续哪些区域会跟着刷新。

@State isShow: boolean = true

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Badge 在头像/图片上')
            .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FFA500').margin({ bottom: 4 })
          Text('用户头像角标：在线状态（绿点）/ 未读消息（红数）/ 身份标识')
            .fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({ bottom: 12 })
        }
        .width('100%').alignItems(HorizontalAlign.Start)

        Row() {
          ForEach([
            { avatar: '1', name: 'Alice', badge: 3, dot: false, color: '#FA2A2D' },
            { avatar: '2', name: 'Bob', badge: 0, dot: true, color: '#6BCB77' },
            { avatar: '3', name: 'Cathy', badge: 99, dot: false, color: '#FA2A2D' },
            { avatar: '4', name: 'David', badge: 0, dot: true, color: '#FFA500' }
          ], (item: BadgeOnAvatarStatusItem) => {
            Column() {
              Badge({
                count: item.dot ? 0 : (item.badge),
                position: BadgePosition.RightTop,

这一段我通常不会一下翻过去，而是先确认下面这几个判断点：

• @State 字段到底在控制显示、选择、跳转结果还是模式切换。
• 默认值是不是合理，页面一打开会不会就落在一个可理解的状态上。
• 字段命名能不能让后来的人一眼看懂用途，而不是还要翻半天 UI。

第二段关键代码：真正决定交互手感的地方

头像场景里，这段代码最值得看的是 count 和 dot 的互斥关系。它没有同时展示数字和状态点，而是根据 item.dot 决定当前头像表达“在线状态”还是“未读数量”。

/**
 * 头像徽章状态页
 */
import { PRESET_COLORS, DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'


interface BadgeOnAvatarStatusItem {
  avatar: string
  name: string
  badge: number
  dot: boolean
  color: string
}
@Entry
@Component
struct BadgeOnAvatarStatus {
  @State isShow: boolean = true

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Badge 在头像/图片上')
            .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FFA500').margin({ bottom: 4 })

代码读到这里，我通常会顺手补三件事，不然后面很容易只看热闹：

1. 这个交互入口接收的到底是什么输入。
2. 输入进来之后，代码改了哪个状态，或者触发了哪次导航。
3. 变化发生后，用户最先感知到的反馈会落在哪个区域。

这三个问题串起来之后，这一页基本就不只是“看过”，而是真的读懂了。

如果你要亲手试，顺序最好别乱

如果你准备把这个案例交给团队里别的人看，我甚至建议直接让对方按下面的顺序自己操作一遍。很多理解偏差都会在这一步消失。

1. 先进入页面，确认首屏是不是把 头像徽章状态页 的主题交代清楚。
2. 盯住核心展示区，观察默认状态下最醒目的内容是什么。
3. 主动触发一次关键交互，比如点击、滑动、跳转、返回、切换或者选择。
4. 回头检查状态区、提示区、标题区或者附属信息有没有跟着变化。
5. 最后再打开源码，对照刚才那次交互，把状态变化链路串起来。

如果这五步你能边操作边说清楚页面发生了什么，后面再换成自己的数据和交互，心里会稳很多。

真放到业务里，我会先改什么

从教程页到业务页，差的从来不只是接口。更多时候，是组件职责、命名和状态来源要重新收拾一遍。

• 徽章进入真实项目后，先统一语义：到底是在表达提醒、数量还是状态，再决定颜色和样式。
• Badge 很容易写散，建议尽早抽一层可复用封装，把颜色、位置和上限逻辑一起收进去。
• 只要页面里有重复块，就别硬撑着手写到底；早点抽成小组件，后面改样式和改交互都会轻松很多。
• 示例数据最好和布局代码分开放，不然后面一接接口，页面文件很容易立刻变臃肿。

它的参考价值不只是把效果跑出来

很多官方示例的价值在于展示组件存在过，但这种页面更进一步：它在展示“组件被放进页面之后怎么活起来”。

• 页面结构比较稳，后续不管是换数据还是换皮肤，成本都不会特别高。
• 状态数量总体可控，适合拿来练“一个页面里如何分配职责”这件事。
• 组件参数和页面目标之间关系比较直观，不太会出现“能跑但看不懂为什么这么配”的情况。

完整代码

下面保留整理过命名的完整 ArkTS 代码，方便你直接对照学习。这里已经去掉原始的 Demo 命名，改成了更贴近当前案例语义的名称。

/**
 * 头像徽章状态页
 */
import { PRESET_COLORS, DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'


interface BadgeOnAvatarStatusItem {
  avatar: string
  name: string
  badge: number
  dot: boolean
  color: string
}
@Entry
@Component
struct BadgeOnAvatarStatus {
  @State isShow: boolean = true

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Badge 在头像/图片上')
            .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FFA500').margin({ bottom: 4 })
          Text('用户头像角标：在线状态（绿点）/ 未读消息（红数）/ 身份标识')
            .fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({ bottom: 12 })
        }
        .width('100%').alignItems(HorizontalAlign.Start)

        Row() {
          ForEach([
            { avatar: '1', name: 'Alice', badge: 3, dot: false, color: '#FA2A2D' },
            { avatar: '2', name: 'Bob', badge: 0, dot: true, color: '#6BCB77' },
            { avatar: '3', name: 'Cathy', badge: 99, dot: false, color: '#FA2A2D' },
            { avatar: '4', name: 'David', badge: 0, dot: true, color: '#FFA500' }
          ], (item: BadgeOnAvatarStatusItem) => {
            Column() {
              Badge({
                count: item.dot ? 0 : (item.badge),
                position: BadgePosition.RightTop,
                maxCount: 99,
                style: { badgeSize: item.dot ? 12 : 16, badgeColor: item.color as string }
              }) {
                Column() {
                  Text(item.avatar as string).fontSize(32).fontWeight(FontWeight.Bold).fontColor('#FFFFFF')
                }
                .width(72).height(72)
                .backgroundColor(item.color as string)
                .borderRadius(36)
                .justifyContent(FlexAlign.Center)
                .border({ width: 2, color: '#FFFFFF' })
                .shadow({ radius: 8, color: '#00000015' })
              }
              Text(item.name as string).fontSize(13).fontColor('#333').margin({ top: 8 })
              if (item.dot) {
                Text('在线').fontSize(10).fontColor('#999').margin({ top: 2 })
              } else {
                Text(item.badge + '条').fontSize(10).fontColor('#999').margin({ top: 2 })
              }
            }.margin({ right: 20 })
          })
        }.width('100%').justifyContent(FlexAlign.Center)
        .backgroundColor(DEMO_CARD_COLOR).borderRadius(12).padding(20)
      }
      Text('头像徽章状态页 - Badge 在头像：在线状态 + 未读消息角标')
        .fontSize(12).fontColor('#999999').margin({ top: 12 })
    }
    .width('100%').height('100%').backgroundColor('#F5F6FA').padding(16)
  }
}

收个尾

如果你最近正好在做 IM、社交或者成员管理一类页面，这篇很适合当起步参考。先把结构跑通，再慢慢替换成自己的数据和交互，效率会高不少。