在做 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
@Component
struct 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 提供的一个非常轻巧但功能强大的提醒类组件，用起来简单但场景应用非常丰富。如果你正在做一个多页面结构、或者内容多状态变化频繁的界面，这个组件一定不要错过。