在做 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 = 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 会自动隐藏，且带缩放过渡。
注意事项
-
Badge 只支持包裹一个子组件（比如图标、文字等）； - 你可以动态控制
count 和 value 来触发显隐； - 对于布局来说，
Badge 是个装饰性组件，不会影响内部子组件的结构； -
value: '' 时默认只显示红点，不展示文本； - 不建议对
Badge 的子组件设置 padding 影响布局，可以用外部容器包一层做空间控制。
使用建议
- 如果你只想要一个小红点状态提示，用
value: '' 是最省事的； - 如果要提示数量，用
count + maxCount 组合； - 如果你希望用户明确看到变化，用
scale 动效的显隐可以提升交互感知； - 在搭配导航栏、列表项、图标按钮时都非常适用。
结语
Badge 是 HarmonyOS ArkUI 提供的一个非常轻巧但功能强大的提醒类组件，用起来简单但场景应用非常丰富。如果你正在做一个多页面结构、或者内容多状态变化频繁的界面，这个组件一定不要错过。
| 技术栈标签 | HarmonyOS 语言 |
|---|---|
| 行业标签 | 工具效率 |
