当前位置：首页 > news >正文

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

news 来源：原创 2025/6/3 18:02:23

在做 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+，这种设计非常适合社交消息、系统通知等消息类提醒。

核心参数快速解释

参数名	用途	示例
`value`	传入字符串作为内容	`'New'`
`count`	传入数字作为提醒数量	`88`
`maxCount`	显示上限，超过显示“+”	`99`
`position`	标记的位置	`BadgePosition.RightTop`
`style`	样式对象，详见下表	`{ badgeSize: 16, badgeColor: '#FA2A2D' }`

style 对象支持的字段：

badgeSize: 标记直径（如 16vp）
badgeColor: 背景色
color: 字体颜色
fontSize: 文本大小
fontWeight: 字体粗细
borderColor: 边框颜色
borderWidth: 边框宽度

动效说明（API v12+）

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

@Entry
@Component
struct BadgeExample {@State badgeCount: number = 1build() {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 会自动隐藏，且带缩放过渡。

在这里插入图片描述