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

文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载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参数说明参数名类型必填默认值说明countInt32是-命名参数。设置提醒消息数。小于等于 0 时不显示信息标记。style?BadgeStyle是-命名参数。Badge 组件可设置的样式支持设置文本颜色、尺寸、圆点颜色和尺寸。position?BadgePosition否None命名参数。提示点显示位置。初始值BadgePosition.RightTopmaxCount?Int32否None命名参数。最大消息数超过最大消息时仅显示maxCount。初始值99child() - Unit是-命名参数。容器的子组件。需要特别注意两个与显示逻辑强相关的参数count 0 时标记不显示这一特性常被用于状态控制角标显隐的场景见下文示例 2maxCount 设置上限当实际消息数超过上限时角标会显示为99这类截断形式避免长数字溢出标记区域。按字符串创建init(String, ?BadgeStyle, ?BadgePosition, () - Unit)public init(value!: String, style!: ?BadgeStyle, position!: ?BadgePosition None, child!: () - Unit)功能根据字符串创建标记组件用于展示 new、热 等文本提示。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22参数说明参数名类型必填默认值说明valueString是-命名参数。文本标记组件参数。style?BadgeStyle是-命名参数。Badge 组件可设置的样式支持设置文本颜色、尺寸、圆点颜色和尺寸。position?BadgePosition否None命名参数。提示点显示位置。初始值BadgePosition.RightTopchild() - Unit是-命名参数。容器的子组件。技巧当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时以命名参数传入也可在创建对象后直接修改。字段类型默认值说明color?ResourceColorColor.White文本颜色fontSize?Length10.fp文本大小单位为 fpbadgeSize?Length16.vpbadge 的大小单位为 vpbadgeColor?ResourceColorColor.Redbadge 的颜色borderColor?ResourceColorColor.Red底板描边颜色borderWidth?Length1.vp底板描边粗细fontWeight?FontWeightFontWeight.Normal文本的字体粗细说明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 : EquatableBadgePosition { | RightTop | Right | Left | ... }父类型EquatableBadgePosition功能定义 badge 位置属性。枚举值说明枚举值显示位置RightTopbadge 显示在父组件的右上角默认值Rightbadge 显示在父组件的右侧纵向居中Leftbadge 显示在父组件的左侧纵向居中枚举比较运算符由于BadgePosition继承自EquatableBadgePosition其提供了两个比较运算符便于在业务逻辑中判断当前标记位置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 信息标记组件梳理了以下关键能力两种创建方式按数字创建countmaxCount与按字符串创建value并掌握count 0隐藏标记、value 退化为圆点等行为特性样式定制通过BadgeStyle的 7 个字段控制文本颜色、字号fp、角标尺寸vp、底色、描边与字重全部参数均有默认值可按需覆盖位置控制BadgePosition提供右上角、右侧居中、左侧居中三种摆放位置实战组合结合State状态管理实现标记显隐联动结合ListItem实现消息列表未读角标。相关参考资源Badge API 文档本文依据公共类型定义ResourceColor / Length / FontWeight列表开发指南给列表项添加标记渲染控制if/else 与 ForEach、LazyForEach赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉 ArkUI 按钮组件Button开发指南创建、样式、事件与场景实战仓颉 ArkUI 按钮组件Button开发指南创建、样式、事件与场景实战 Button 是 ArkUI 中最常用的交互组件用于响应用户点击操作支持胶囊文档知识库教程OpenHarmony仓颉 ArkUI 切换按钮 Toggle 组件开发指南三种样式、状态切换与 onChange 事件实战仓颉 ArkUI 切换按钮 Toggle 组件开发指南三种样式、状态切换与 onChange 事件实战 Toggle 是仓颉声明式开发范式中用于两种状态之间切文档知识库教程OpenHarmony仓颉 ArkUI transition 组件内转场实战TransitionEffect 全 API 解析与示例仓颉 ArkUI transition 组件内转场实战TransitionEffect 全 API 解析与示例 本文围绕仓颉CangjieArkUI 框架文档知识库教程OpenHarmony上一篇flet-camera CameraStateEvent 详解相机状态事件字段、触发机制与实战用法下一篇OKX Agentic Wallet Gas Station 完全指南用 USDT/USDC/USDG 稳定币支付 Solana Gas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考