HarmonyOS7列表项徽章提示页实战：Badge 在列表行中的挂载方式

yangcy9

73人浏览 · 2026-07-21 09:43:03

yangcy9 · 2026-07-21 09:43:03 发布

文章目录

前言

当徽章不再挂在图标上，而是挂在列表项上时，页面逻辑就开始接近真实业务了。订单状态、消息未读、功能推荐，这些都很常见。这个案例的业务味比较强。真到项目里，很多问题都不是“会不会用组件”，而是“这个组件放在当前页面里顺不顺手”。所以这篇不会只盯 API，而是把页面结构、交互反馈和后续扩展一起看。

别看这个案例篇幅不算长，但它很适合拿来练“页面目标和代码结构怎么对齐”这件事。你后面不管是复刻，还是准备拆成自己的业务组件，都会更顺。

这类写法尤其适合落在设置页、消息列表、功能中心、订单入口这些场景里，所以我下面不会只讲“组件怎么写”，而是更关心“放进页面之后为什么这样组织”。

A hand-drawn doodle illustration on pure white pap

真正值得先看的不是细节代码

如果你已经打开运行效果，会更容易理解这一段。因为这页并不是靠某一个孤立控件撑起来的，而是几个区域互相配合才成立。

A hand-drawn doodle illustration on pure white pap

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

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

如果你不是只想看懂，而是准备拿去改，这篇更关注哪些区域适合抽离、复用和替换。

列表里的 Badge，要和每一行数据绑在一起看

这页的关键不是 isShow，而是 messages 这组列表数据。每一行里的 name、avatar、unread、time 共同组成一条会话摘要，Badge 只是把其中最需要用户注意的 unread 放大了。

读这类页面时，我建议按行来建模：

谁发来的：name 和 avatar 负责建立识别感。
什么时候来的：time 帮用户判断消息新旧。
要不要处理：unread 才是 Badge 的数据来源，决定这一行有没有提醒价值。

所以 Badge 挂在列表项上时，不能只看角标本身。它必须服务于整行信息排序：用户扫一眼列表，就应该知道哪几条最值得先点开。

代码别平均看，先抓关键方法

如果你想更快进入状态，可以把这些方法当成页面的控制台。哪个方法被触发，页面就往哪个方向走。

A hand-drawn doodle illustration on pure white pap

Badge：读它时重点看输入、改动对象，以及它最终影响了页面哪一块。

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

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

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

@State isShow: boolean = true
  private messages: BadgeOnListItemsItem[] = [
    { name: '张三', avatar: '👤', unread: 3, time: '10:30' },
    { name: '李四', avatar: '👩', unread: 0, time: '09:15' },
    { name: '王五', avatar: '👨', unread: 99, time: '昨天' },
    { name: '赵六', avatar: '🧑', unread: 1, time: '周一' },
    { name: '孙七', avatar: '👧', unread: 0, time: '上周' }
  ]

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Badge 在列表项上')
            .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FF6B9D').margin({ bottom: 4 })
          Text('消息列表项右侧显示 Badge 未读数，模拟聊天列表')
            .fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({ bottom: 12 })
        }
        .width('100%').alignItems(HorizontalAlign.Start)

        List() {
          ForEach(this.messages, (msg: BadgeOnListItemsItem, idx: number) => {
            ListItem() {
              Row() {

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

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

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

这段代码已经很接近真实消息列表了。Badge 没有孤立出现，而是挂在每个 ListItem 的右侧，用 msg.unread 把提醒数量和当前行数据绑定起来。

Badge({
                  count: msg.unread as number,
                  position: BadgePosition.Right,
                  maxCount: 99,
                  style: { badgeSize: 18, badgeColor: '#FA2A2D', fontSize: 10 }
                }) {
                  Text('')
                }
              }
              .width('100%').height(64).padding({ left: 16, right: 16 })
              .alignItems(VerticalAlign.Center)
            }
            .border({ width: { bottom: 0.5 }, color: '#F0F0F0' })
          })
        }
        .width('100%').height(340)
        .backgroundColor(DEMO_CARD_COLOR)
        .borderRadius(12)
        .divider({ strokeWidth: 0 })
      }
      Text('列表项徽章提示页 - Badge 在列表项：消息未读数量展示')
        .fontSize(12).fontColor('#999999').margin({ top: 12 })
    }
    .width('100%').height('100%').backgroundColor('#F5F6FA').padding(16)

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

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

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

不是只看，最好按这个顺序动手

我比较推荐用“观察 -> 触发 -> 对照源码”的方式学这个页面。先看到效果，再回去找原因，记得会更牢。

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

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

拿去项目里之前，我通常会做这些调整

如果只把这页当 demo 看，它的价值其实只发挥了一半。更值得做的，是顺手想一遍：放进项目之后哪里该抽，哪里该换，哪里该收口。

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

这页不复杂，但很适合当模板

如果你经常做业务页，会发现这种案例特别适合复用思路。它不像单纯 API 示例那样看完就过去。

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

完整代码

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

/**
 * 列表项徽章提示页
 */
import { PRESET_COLORS, generateListItems, DEMO_BG_COLOR, DEMO_CARD_COLOR, DEMO_THEME_COLOR, DEMO_SUBTEXT_COLOR } from './types'


interface BadgeOnListItemsItem {
  name: string
  avatar: string
  unread: number
  time: string
}
@Entry
@Component
struct BadgeOnListItems {
  @State isShow: boolean = true
  private messages: BadgeOnListItemsItem[] = [
    { name: '张三', avatar: '👤', unread: 3, time: '10:30' },
    { name: '李四', avatar: '👩', unread: 0, time: '09:15' },
    { name: '王五', avatar: '👨', unread: 99, time: '昨天' },
    { name: '赵六', avatar: '🧑', unread: 1, time: '周一' },
    { name: '孙七', avatar: '👧', unread: 0, time: '上周' }
  ]

  build() {
    Column() {
      if (this.isShow) {
        Column() {
          Text('Badge 在列表项上')
            .fontSize(18).fontWeight(FontWeight.Bold).fontColor('#FF6B9D').margin({ bottom: 4 })
          Text('消息列表项右侧显示 Badge 未读数，模拟聊天列表')
            .fontSize(12).fontColor(DEMO_SUBTEXT_COLOR).margin({ bottom: 12 })
        }
        .width('100%').alignItems(HorizontalAlign.Start)

        List() {
          ForEach(this.messages, (msg: BadgeOnListItemsItem, idx: number) => {
            ListItem() {
              Row() {
                Text(msg.avatar).fontSize(36)
                Column() {
                  Text(msg.name).fontSize(15).fontWeight(FontWeight.Medium).fontColor('#333')
                  Text('最后消息时间 ' + (msg.time as string)).fontSize(11).fontColor('#999').margin({ top: 2 })
                }.alignItems(HorizontalAlign.Start).margin({ left: 12 }).layoutWeight(1)

                Badge({
                  count: msg.unread as number,
                  position: BadgePosition.Right,
                  maxCount: 99,
                  style: { badgeSize: 18, badgeColor: '#FA2A2D', fontSize: 10 }
                }) {
                  Text('')
                }
              }
              .width('100%').height(64).padding({ left: 16, right: 16 })
              .alignItems(VerticalAlign.Center)
            }
            .border({ width: { bottom: 0.5 }, color: '#F0F0F0' })
          })
        }
        .width('100%').height(340)
        .backgroundColor(DEMO_CARD_COLOR)
        .borderRadius(12)
        .divider({ strokeWidth: 0 })
      }
      Text('列表项徽章提示页 - Badge 在列表项：消息未读数量展示')
        .fontSize(12).fontColor('#999999').margin({ top: 12 })
    }
    .width('100%').height('100%').backgroundColor('#F5F6FA').padding(16)
  }
}