仓颉 ArkUI Badge 信息标记组件开发指南：用法、样式与实战示例

• 文档
• 知识库
• 教程
• OpenHarmony

Badge 是仓颉 ArkUI 中用于在单个组件上附加信息提醒的容器组件，常用于消息未读数、新内容提示等场景。本文基于仓颉语言语料库中 cj-information-display-badge.md 的 API 文档，系统讲解 Badge 的两种创建方式、BadgeStyle样式体系、BadgePosition位置枚举，并给出可运行示例与列表场景中的实战用法，帮助你快速掌握在鸿蒙应用中集成信息标记的能力。

Badge 组件概述

Badge（信息标记组件）可以附加在单个组件上，用于信息提醒，典型形态包括数字角标、文本角标和纯圆点标记。它的使用方式非常直接：将需要被标记的业务组件（如按钮、头像、文本卡片）作为 Badge 的唯一子组件传入，Badge 会自动在该组件边缘位置叠加标记内容。

导入模块

使用 Badge 前，需要在仓颉源文件中导入 ArkUI 声明式开发框架的包：

import kit.ArkUI.*

子组件约束

Badge 支持单个子组件，且对子组件类型没有过多限制：

• 系统组件与自定义组件均可作为子组件；
• 支持渲染控制类型，包括 if/else、ForEach、LazyForEach。

这意味着你可以通过条件渲染或循环渲染动态决定被标记组件的内容，也可以结合@State状态变量实现标记的显隐与数值联动。

创建 Badge 组件

Badge 提供了两个构造函数（init），分别用于按数字创建和按字符串创建。

按数字创建：init(Int32, ?BadgeStyle, ?BadgePosition, ?Int32, () -> Unit)

public init(count!: Int32, style!: ?BadgeStyle, position!: ?BadgePosition = None, maxCount!: ?Int32 = None, child!: () -> Unit)

功能：根据数字创建标记组件，用于展示消息数量角标。

系统能力：SystemCapability.ArkUI.ArkUI.Full

起始版本：22

参数说明：

需要特别注意两个与显示逻辑强相关的参数：

• count <= 0 时标记不显示，这一特性常被用于"状态控制角标显隐"的场景（见下文示例 2）；
• maxCount 设置上限，当实际消息数超过上限时，角标会显示为99+这类截断形式，避免长数字溢出标记区域。

按字符串创建：init(String, ?BadgeStyle, ?BadgePosition, () -> Unit)

public init(value!: String, style!: ?BadgeStyle, position!: ?BadgePosition = None, child!: () -> Unit)

功能：根据字符串创建标记组件，用于展示 "new"、"热" 等文本提示。

系统能力：SystemCapability.ArkUI.ArkUI.Full

起始版本：22

参数说明：

技巧：当value传入空字符串""时，Badge 不再显示文本，而是退化为一个纯圆点标记。这一行为常用于"有未读状态即点亮红点"的轻量提示场景。

BadgeStyle：标记样式类

BadgeStyle封装了 Badge 的全部外观参数，覆盖文本、底色、圆点、边框和字重等维度。

public class BadgeStyle { public var color: ?ResourceColor public var fontSize: ?Length public var badgeSize: ?Length public var badgeColor: ?ResourceColor public var fontWeight: ?FontWeight public var borderColor: ?ResourceColor public var borderWidth: ?Length public init(color!: ?ResourceColor = None, fontSize!: ?Length = None, badgeSize!: ?Length = None, badgeColor!: ?ResourceColor = None, borderColor!: ?ResourceColor = None, borderWidth!: ?Length = None, fontWeight!: ?FontWeight = None) }

功能：包含 Badge 组件的样式参数。

系统能力：SystemCapability.ArkUI.ArkUI.Full

起始版本：22

字段与构造参数详解

所有字段均为public var，可读写，既可在构造BadgeStyle时以命名参数传入，也可在创建对象后直接修改。

说明：Length是长度类型接口，Float64、Int64、AppResource均实现了Length接口，因此既可传入16这类数值，也可传入10.fp、2.vp等带单位后缀的写法；ResourceColor是颜色类型接口，Color、UInt32、Int64、AppResource均实现了该接口，示例代码中Color.Red、Color(0xFFFFFF)、0x317aff都是合法取值。

BadgePosition：标记位置枚举

BadgePosition定义了标记在父组件上的显示位置：

public enum BadgePosition <: Equatable<BadgePosition> { | RightTop | Right | Left | ... }

父类型：Equatable<BadgePosition>

功能：定义 badge 位置属性。

枚举值说明

枚举比较运算符

由于BadgePosition继承自Equatable<BadgePosition>，其提供了两个比较运算符，便于在业务逻辑中判断当前标记位置：

public operator func ==(other: BadgePosition): Bool public operator func !=(other: BadgePosition): Bool

• ==：两个枚举值相等返回true，否则返回false；
• !=：两个枚举值不相等返回true，否则返回false。

通用属性与通用事件

Badge 本身是容器组件，对外部属性与事件的支持情况如下：

• 通用属性：除文本样式（如fontColor、fontSize等文本类属性）外，其余通用属性全部支持；
• 通用事件：全部支持。

这意味着你可以对 Badge 直接设置尺寸、背景、边框、透明度、点击事件等通用能力，被标记的子组件仍可独立承载各自的交互逻辑。

示例 1：设置标记组件内容

该示例通过value和count属性，演示传入数字、字符串及空字符串时标记组件展现的不同效果。示例同时覆盖了三种BadgePosition与多种BadgeStyle组合。

package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* @Entry @Component class EntryView { func build() { Column() { Text("numberBadge").width(80.percent) Row(space: 10) { // 数字上标，maxCount默认99,超过99展示99+ Badge( count: 1, style: BadgeStyle(color: Color(0xFFFFFF), fontSize: 16, badgeSize: 20, badgeColor: Color.Red, fontWeight: FontWeight.Bolder, borderColor: Color.Black, borderWidth: 2.vp), position: BadgePosition.RightTop, maxCount: 99 ) { Button("message").width(100).height(50).backgroundColor(0x317aff) }.width(100).height(50) Badge( count: 1, style: BadgeStyle(color: Color(0xFFFFFF), fontSize: 16, badgeSize: 20, badgeColor: Color.Red, fontWeight: FontWeight.Bolder, borderColor: Color.Green, borderWidth: 2.vp), position: BadgePosition.Left, maxCount: 99 ) { Button("message").width(100).height(50).backgroundColor(0x317aff) }.width(100).height(50) // 数字上标 Badge( count: 1, style: BadgeStyle(color: Color(0xFFFFFF), fontSize: 16, badgeSize: 20, badgeColor: Color.Red, fontWeight: FontWeight.Regular, borderColor: Color.Gray, borderWidth: 4.vp), position: BadgePosition.Right, maxCount: 99 ) { Button("message").width(100).height(50).backgroundColor(0x317aff) }.width(100).height(50) }.margin(10) Text("stringBadge").width(80.percent) Row(space: 30) { Badge( value: "new", style: BadgeStyle(color: Color(0xFFFFFF), fontSize: 9, badgeSize: 20, badgeColor: Color.Blue) ) { Text("message") .width(80) .height(50) .fontSize(16) .lineHeight(37) .borderRadius(10) .textAlign(TextAlign.Center) .backgroundColor(0xF3F4ED) }.width(80).height(50) // value为空，设置圆点标记 Badge( value: "", style: BadgeStyle(badgeSize: 6, badgeColor: Color.Blue), position: BadgePosition.Right ) { Text("message") .width(90) .height(50) .fontSize(16) .lineHeight(37) .borderRadius(10) .textAlign(TextAlign.Center) .backgroundColor(0xF3F4ED) }.width(90).height(50) }.margin(10) } } }

效果解读：

• 第一行numberBadge中，三个 Badge 均以count: 1创建数字角标，分别展示在按钮的右上角（RightTop）、左侧（Left）、右侧居中（Right）位置，通过改变borderColor、borderWidth、fontWeight演示了不同视觉风格；
• 第二行stringBadge中，左侧 Badge 以value: "new"创建文本标记；右侧 Badge 以value: ""加badgeSize: 6的样式退化为纯圆点标记。

示例 2：设置数字控制标记显隐

该示例通过count属性，演示设置数字 0 和 1 时标记组件的隐藏与显示效果，是"未读消息红点开关"类功能的典型实现。

package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* @Entry @Component class EntryView { @State var badgeCount: Int32 = 1 func build() { Column() { Badge( count: this.badgeCount, style: BadgeStyle(color: Color(0xFFFFFF), fontSize: 16, badgeSize: 20, badgeColor: Color.Red,fontWeight: FontWeight.Bolder, borderColor: Color.Black, borderWidth: 2.vp), position: BadgePosition.RightTop, ){ Text("message") .width(100) .height(50) .backgroundColor(0x317aff) } .width(100) .height(50) Button("count 0") .onClick({ evt => this.badgeCount =0;}) Button("count 1") .onClick({ evt => this.badgeCount =1;}) }.margin(10) } }

实现原理：

• 通过@State var badgeCount: Int32声明状态变量，并将它绑定到 Badge 的count参数；
• 点击count 0按钮时，badgeCount置为 0，由于 count <= 0 不显示信息标记，角标立即消失；
• 点击count 1按钮时，badgeCount恢复为 1，角标重新出现。

借助仓颉 ArkUI 的状态管理机制，Badge 的显隐与真实消息数之间形成了自动同步，无需手动增删组件节点。这也是状态驱动 UI 的标准写法：数据一变，标记随之更新。

实战：在列表项上添加未读标记

Badge 的典型应用场景是在消息列表的联系人头像右上角叠加未读标记。在仓颉 ArkUI 的列表开发指南 cj-layout-development-create-list.md 中给出了这一用法：将头像Image组件作为 Badge 的子组件，再将该 Badge 放入ListItem中，即可为列表项添加标记功能。

ListItem(){ Badge( count: 1, style: BadgeStyle(color: 0xfa2a2d, badgeSize: 16), position: BadgePosition.RightTop, child: { => Image(@r(app.media.startIcon)) } ) }

要点说明：

• 以count设置消息数量，以position: BadgePosition.RightTop将标记定位在头像右上角（符合移动端未读角标的通用视觉规范）；
• 通过style仅指定color与badgeSize，其余样式参数采用默认值，即可获得简洁的红色数字角标；
• 标记只显示在单个列表项上，是一种无干扰性且直观的通知呈现方式，常用于消息列表、待办事项等需要局部注意力引导的界面。

小结

本文围绕仓颉 ArkUI 的 Badge 信息标记组件，梳理了以下关键能力：

1. 两种创建方式：按数字创建（count+maxCount）与按字符串创建（value），并掌握count <= 0隐藏标记、value = ""退化为圆点等行为特性；
2. 样式定制：通过BadgeStyle的 7 个字段控制文本颜色、字号（fp）、角标尺寸（vp）、底色、描边与字重，全部参数均有默认值，可按需覆盖；
3. 位置控制：BadgePosition提供右上角、右侧居中、左侧居中三种摆放位置；
4. 实战组合：结合@State状态管理实现标记显隐联动，结合ListItem实现消息列表未读角标。

相关参考资源：

• Badge API 文档（本文依据）
• 公共类型定义（ResourceColor / Length / FontWeight）
• 列表开发指南：给列表项添加标记
• 渲染控制：if/else 与 ForEach、LazyForEach

• 文档
• 知识库
• 教程
• OpenHarmony