鸿蒙 ArkTS | Badge 信息标记组件自学指南

在做 UI 设计时，我们经常会碰到这样一个需求：要在某个图标、按钮或列表项的角落加一个小小的提示，比如红点、新消息数量、状态标签之类的。这时候就轮到 ​​Badge​​ 组件登场了。

如果你想要一个简单优雅、可配置灵活的信息标记功能，​​Badge​​ 就是官方给你的标准答案。

组件简介：Badge 是干什么的？

​​Badge​​ 是一个「信息标记容器组件」，可以附加在你指定的任何子组件上，用来做提示提醒，比如：

• 红点

• 数字（1~99+）

• 文本（"New"、"Hot"）

而且它支持位置设置、样式自定义，还能根据不同的数据类型进行不同展示，非常适合做复杂场景下的状态提示。

基本用法：数字、文本、红点分别怎么玩？

我们直接看代码，分三个小案例逐一拆解。

示例一：红点提示（不显示内容，只显示圆点）

Badge({  value: '',  style: {    badgeSize: 6, // 圆点直径    badgeColor: '#FA2A2D' // 红点颜色  }}) {  Image('/common/public_icon_off.svg')    .width(24)    .height(24)}

这种场景适合用在有无状态表示，比如有没有新消息、开关状态变更等场合。

示例二：文字提示（显示"New"）

Badge({  value: 'New',  position: BadgePosition.Right,  style: {    badgeSize: 16,    badgeColor: '#FA2A2D'  }}) {  Text('列表项')    .fontSize(14)    .fontColor('#182431')}

这个就更适合做文字标签，比如「NEW」「HOT」「升级」「试用」等场景，跟着组件一起展示。

示例三：数字提示（显示数量）

Badge({  count: 88,  maxCount: 99,  position: BadgePosition.Right,  style: {    badgeSize: 16,    badgeColor: '#FA2A2D'  }}) {  Image('common/public_icon.svg')    .width(32)    .height(32)}

当 ​​count​​​ 超过 ​​maxCount​​​ 后，会自动变成 ​​99+​​，这种设计非常适合社交消息、系统通知等消息类提醒。

核心参数快速解释

style 对象支持的字段：

• ​​badgeSize​​​: 标记直径（如 ​​16vp​​）

• ​​badgeColor​​: 背景色

• ​​color​​: 字体颜色

• ​​fontSize​​: 文本大小

• ​​fontWeight​​: 字体粗细

• ​​borderColor​​: 边框颜色

• ​​borderWidth​​: 边框宽度

动效说明（API v12+）

从 API v12 开始，Badge 的显隐可以带 ​​scale​​​ 动效，默认开启，不需要额外配置。只要你动态控制 ​​count​​​ 或 ​​value​​，它就能自动执行缩放效果，比如下方这个例子：

@Entry@Componentstruct BadgeExample {  @State badgeCount: number = 1  build() {    Row(){      Badge({        count: this.badgeCount,        style: {},        position: BadgePosition.RightTop,      }) {        Image($r("app.media.startIcon"))          .width(50)          .height(50)      }
      Button('隐藏 Badge').onClick(() => {        this.badgeCount = 0      })      Button('显示 Badge').onClick(() => {        this.badgeCount = 5      })    }
  }}

​​count = 0​​ 时 Badge 会自动隐藏，且带缩放过渡。

注意事项

1. ​​Badge​​ 只支持包裹一个子组件（比如图标、文字等）；

2. 你可以动态控制 ​​count​​​ 和 ​​value​​ 来触发显隐；

3. 对于布局来说，​​Badge​​ 是个装饰性组件，不会影响内部子组件的结构；

4. ​​value: ''​​ 时默认只显示红点，不展示文本；

5. 不建议对 ​​Badge​​​ 的子组件设置 ​​padding​​ 影响布局，可以用外部容器包一层做空间控制。

使用建议

• 如果你只想要一个小红点状态提示，用 ​​value: ''​​ 是最省事的；

• 如果要提示数量，用 ​​count + maxCount​​ 组合；

• 如果你希望用户明确看到变化，用 ​​scale​​ 动效的显隐可以提升交互感知；

• 在搭配导航栏、列表项、图标按钮时都非常适用。

结语

Badge 是 HarmonyOS ArkUI 提供的一个非常轻巧但功能强大的提醒类组件，用起来简单但场景应用非常丰富。如果你正在做一个多页面结构、或者内容多状态变化频繁的界面，这个组件一定不要错过。