HarmonyOS 6 Badge 标记组件使用示例文档

harmonyOS 6 Badge 标记组件使用示例文档

组件介绍

Badge（标记组件）是HarmonyOS ArkTS中用于在UI元素上展示角标、红点、数字/文本提示的容器组件，常用于消息提醒、状态标记等场景（如未读消息数、新功能提示、异常状态红点等）。本文基于示例代码，详细讲解Badge组件的核心使用方式。

示例代码功能说明

本示例代码展示了Badge组件三种典型使用场景：

1. 红点标记：Tabs标签栏中展示无数字/文本的红点提示；
2. 文本标记：List列表项中展示“New”文本提示；
3. 数字标记：List列表项中展示数字计数提示。

核心API与参数

1. Badge组件构造参数

2. 关键枚举

• BadgePosition：标记位置枚举，示例中使用BadgePosition.Right（右侧）；
• FlexAlign：布局对齐枚举，示例中用于Column的居中对齐；
• Alignment：组件对齐枚举，示例中用于ListItem的内容对齐。

代码分段解析

1. 红点标记（Tabs标签栏）

@Builder tabBuilder(index: number) { Column() { if (index === 2) { Badge({ value: '', // 空值实现纯红点效果 style: { badgeSize: 6, badgeColor: '#FA2A2D' } // 红点尺寸6px，红色 }) { Image('/common/public_icon_off.svg') .width(24) .height(24) } .width(24) .height(24) .margin({ bottom: 4 }) } else { // 非目标标签，仅展示图标 Image('/common/public_icon_off.svg') .width(24) .height(24) .margin({ bottom: 4 }) } // 标签文本 Text('Tab') .fontColor('#182431') .fontSize(10) .fontWeight(500) .lineHeight(14) }.width('100%').height('100%').justifyContent(FlexAlign.Center) }

说明：

• 通过value: ''设置空文本，结合badgeSize: 6实现小尺寸红点；
• badgeColor: '#FA2A2D'设置红点为红色（告警色）；
• 仅在第3个Tab（index=2）展示红点，其余Tab仅展示图标。

2. 文本标记（List列表项）

ListItem() { Badge({ value: 'New', // 文本标记内容 position: BadgePosition.Right, // 标记显示在文本右侧 style: { badgeSize: 16, badgeColor: '#FA2A2D' } // 标记尺寸16px，红色 }) { Text('list2').width(27).height(19).fontSize(14).fontColor('#182431') }.width(49.5).height(19) .margin({ left: 12 }) }

说明：

• value: 'New'设置文本标记，用于提示“新内容”；
• position: BadgePosition.Right指定标记在子组件（Text）右侧；
• badgeSize: 16适配文本“New”的显示尺寸。

3. 数字标记（List列表项）

ListItem() { Row() { Image('common/public_icon.svg').width(32).height(32).opacity(0.6) Badge({ count: 1, // 数字标记内容 position: BadgePosition.Right, // 标记显示在文本右侧 style: { badgeSize: 16, badgeColor: '#FA2A2D' } // 标记尺寸16px，红色 }) { Text('list2') .width(177) .height(21) .textAlign(TextAlign.Start) .fontColor('#182431') .fontWeight(500) .fontSize(16) .opacity(0.9) }.width(240).height(21).margin({ left: 15, right: 11 }) Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6) }.width('100%').padding({ left: 12, right: 12 }).height(56) }

说明：

• count: 1设置数字标记，用于提示“1条未读/未处理项”；
• Badge包裹Text组件，标记跟随文本展示；
• 结合Row布局，与图标、箭头组成完整的列表项样式。

4. 整体布局容器

build() { Column() { // 红点标记展示区 Text('dotsBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) Tabs() { TabContent().tabBar(this.tabBuilder(0)) TabContent().tabBar(this.tabBuilder(1)) TabContent().tabBar(this.tabBuilder(2)) // 展示红点的Tab TabContent().tabBar(this.tabBuilder(3)) }.width(360).height(56).backgroundColor('#F1F3F5') // 文本/数字标记展示区 Column() { // 文本标记List Text('stringBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) List({ space: 12 }) { ... } // 数字标记List Text('numberBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) List() { ... } }.width('100%').backgroundColor('#F1F3F5').padding({ bottom: 12 }) }.width('100%') }

运行效果如图：

说明：

• 整体采用Column纵向布局，分“红点标记”“文本标记”“数字标记”三个区域；
• Tabs组件实现标签栏布局，List组件实现列表布局，Badge作为子组件嵌入对应位置。

效果展示

总结

1. value与count互斥：Badge组件同时只能设置value（文本）或count（数字），不可同时设置；
2. 尺寸适配：badgeSize需根据标记内容调整（如文本“New”需16px以上，红点可设6-8px）；
3. 布局约束：Badge包裹的子组件需设置明确的宽高，避免标记位置偏移；
4. 样式统一：示例中统一使用#FA2A2D（红色）作为标记颜色，符合移动端告警/提示的视觉规范。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力