1# Badge 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @liyujie43--> 5<!--Designer: @weixin_52725220--> 6<!--Tester: @xiong0104--> 7<!--Adviser: @HelloCrease--> 8 9信息标记组件，可以附加在单个组件上用于信息提醒的容器组件。 10 11> **说明：** 12> 13> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 14 15 16## 子组件 17 18支持单个子组件。 19 20> **说明：** 21> 22> 子组件类型：系统组件和自定义组件，支持渲染控制类型（[if/else](../../../ui/state-management/arkts-rendering-control-ifelse.md)、[ForEach](../../../ui/state-management/arkts-rendering-control-foreach.md)和[LazyForEach](../../../ui/state-management/arkts-rendering-control-lazyforeach.md)）。 23> 自定义组件宽高默认为0，需要给其设置宽高，否则标记组件将不显示。 24 25 26## 接口 27 28### Badge 29 30Badge(value: BadgeParamWithNumber) 31 32根据数字创建标记组件。 33 34**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 35 36**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 37 38**系统能力：** SystemCapability.ArkUI.ArkUI.Full 39 40**参数：** 41 42| 参数名 | 类型 | 必填 | 说明 | 43| -------- | -------- | -------- | -------- | 44| value | [BadgeParamWithNumber](#badgeparamwithnumber对象说明)| 是 | 数字标记组件参数。| 45 46### Badge 47 48Badge(value: BadgeParamWithString) 49 50根据字符串创建标记组件。 51 52**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 53 54**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 55 56**系统能力：** SystemCapability.ArkUI.ArkUI.Full 57 58从API version 12开始，该组件显隐时支持scale动效。 59 60**参数：** 61 62| 参数名 | 类型 | 必填 | 说明 | 63| ------ | ----------------------------------------------------- | ---- | -------------------- | 64| value | [BadgeParamWithString](#badgeparamwithstring对象说明) | 是 | 字符串标记组件参数。 | 65 66## BadgeParam对象说明 67 68包含用于创建Badge组件的基础参数。 69 70**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76| 名称 | 类型 | 只读 | 可选 | 说明 | 77| -------- | -------- | -------- | -------- | -------- | 78| position | [BadgePosition](#badgeposition枚举说明)\|[Position<sup>10+</sup>](ts-types.md#position) | 否 | 是 | 设置提示点显示位置。<br/>默认值：BadgePosition.RightTop <br/>**说明：** <br/> Position作为入参，不支持设置百分比；设置为非法值时，默认(0,0)处理。(0,0)为组件左上角位置。<br/>BadgePosition作为入参时，会跟随[Direction](ts-appendix-enums.md#direction)属性控制镜像显示。| 79| style | [BadgeStyle](#badgestyle对象说明) | 否 | 否 | Badge组件可设置样式，支持设置文本颜色、尺寸、圆点颜色和尺寸。 | 80 81 82## BadgeParamWithNumber对象说明 83 84BadgeParamWithNumber继承自[BadgeParam](#badgeparam对象说明)，具有BadgeParam的全部属性。 85 86**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92| 名称 | 类型 | 只读 | 可选 | 说明 | 93| -------- | -------- | -------- | -------- | -------- | 94| count | number | 否 | 否 | 设置提醒消息数。<br/>**说明：** <br/>当该值小于等于0且小于maxCount时不显示信息标记。<br/>取值范围：[-2147483648,2147483647]。超出范围时会加上或减去4294967296，使得值仍在范围内，非整数时会舍去小数部分取整数部分，如5.5取5。 | 95| maxCount | number | 否 | 是 | 最大消息数，超过最大消息时仅显示maxCount+。<br/>默认值：99<br/>取值范围：[-2147483648,2147483647]。超出范围时会加上或减去4294967296，使得值仍在范围内，非整数时会舍去小数部分取整数部分，如5.5取5。 | 96 97## BadgeParamWithString对象说明 98 99BadgeParamWithString继承自[BadgeParam](#badgeparam对象说明)，具有BadgeParam的全部属性。 100 101**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 102 103**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 104 105**系统能力：** SystemCapability.ArkUI.ArkUI.Full 106 107| 名称 | 类型 | 只读 | 可选 | 说明 | 108| -------- | -------- | -------- | -------- | -------- | 109| value | [ResourceStr](ts-types.md#resourcestr) | 否 | 否 | 提示内容的文本字符串。<br/>**说明：** <br/>从API version 20开始，支持ResourceStr类型。 | 110 111## BadgePosition枚举说明 112 113提示点显示位置。 114 115**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 116 117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 118 119**系统能力：** SystemCapability.ArkUI.ArkUI.Full 120 121| 名称 | 值 | 说明 | 122| -------- | -------- |-------- | 123| RightTop | - | 圆点显示在右上角。 | 124| Right | - | 圆点显示在右侧纵向居中。 | 125| Left | - | 圆点显示在左侧纵向居中。 | 126 127## BadgeStyle对象说明 128 129Badge的样式。 130 131**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 132 133**系统能力：** SystemCapability.ArkUI.ArkUI.Full 134 135| 名称 | 类型 | 只读 | 可选 | 说明 | 136| ------------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 137| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 文本颜色。<br/>默认值：Color.White<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 138| fontSize | number \| [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 文本大小。string类型仅支持number类型取值的字符串形式，可以附带单位，例如"10"、"10fp"。<br/>默认值：10<br/>单位：fp<br/>取值范围：大于0；取值为0时不显示文本，取值小于0时取默认值。<br/>**说明：** <br/>不支持设置百分比，当设置为百分比时，按照默认值处理。从API version 20开始，支持ResourceStr类型。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 139| badgeSize | number \| [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | Badge的大小。string类型支持number类型取值的字符串形式，可以附带单位，例如"16"、"16vp"。<br/>默认值：16<br/>单位：vp<br/>取值范围：大于0；取值为0时不显示Badge，取值小于0时取默认值。<br/>**说明：** <br/>不支持设置百分比，当设置为百分比时，按照默认值处理。从API version 20开始，支持ResourceStr类型。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 140| badgeColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | Badge的颜色。<br/>默认值：Color.Red<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 | 141| fontWeight<sup>10+</sup> | number \|[FontWeight](ts-appendix-enums.md#fontweight) \| [ResourceStr](ts-types.md#resourcestr) | 否 | 是 | 设置文本的字体粗细。number类型取值范围：[100, 900]，取值间隔为100。取值越大，字体越粗。设置number类型在取值范围外时，按默认值400处理。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal<br/>**说明：** <br/>不支持设置百分比，当设置为百分比时，按照默认值处理。从API version 20开始，支持ResourceStr类型。 | 142| borderColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 底板描边颜色。<br/>默认值：Color.Red | 143| borderWidth<sup>10+</sup> | [Length](ts-types.md#length) | 否 | 是 | 底板描边粗细。<br/>默认值：1<br/>单位：vp<br/>**说明：** <br/>不支持设置百分比，当设置为百分比时，按照默认值处理。 | 144 145> **说明：** 146> 当`borderWidth`大于0且`borderColor`与`badgeColor`颜色不一致时，先绘制角标，再绘制描边。由于边缘像素经过抗锯齿处理，抗锯齿产生半透明像素，四角会出现 `badgeColor` 颜色的描边线。如需实现相关场景，建议使用[Text](ts-basic-components-text.md)组件设置[outline](ts-universal-attributes-outline.md)代替Badge组件。 147 148## 属性 149 150支持[通用属性](ts-component-general-attributes.md)。 151 152## 事件 153 154支持[通用事件](ts-component-general-events.md)。 155 156## 示例 157 158### 示例1（设置标记组件内容） 159 160该示例通过value和count属性，实现了传入空值、字符、数字时标记组件展现不同的效果。 161 162```ts 163// xxx.ets 164@Entry 165@Component 166struct BadgeExample { 167 @Builder 168 tabBuilder(index: number) { 169 Column() { 170 if (index === 2) { 171 Badge({ 172 value: '', 173 style: { badgeSize: 6, badgeColor: '#FA2A2D' } 174 }) { 175 Image('/common/public_icon_off.svg') 176 .width(24) 177 .height(24) 178 } 179 .width(24) 180 .height(24) 181 .margin({ bottom: 4 }) 182 } else { 183 Image('/common/public_icon_off.svg') 184 .width(24) 185 .height(24) 186 .margin({ bottom: 4 }) 187 } 188 Text('Tab') 189 .fontColor('#182431') 190 .fontSize(10) 191 .fontWeight(500) 192 .lineHeight(14) 193 }.width('100%').height('100%').justifyContent(FlexAlign.Center) 194 } 195 196 @Builder 197 itemBuilder(value: string) { 198 Row() { 199 Image('common/public_icon.svg').width(32).height(32).opacity(0.6) 200 Text(value) 201 .width(177) 202 .height(21) 203 .margin({ left: 15, right: 76 }) 204 .textAlign(TextAlign.Start) 205 .fontColor('#182431') 206 .fontWeight(500) 207 .fontSize(16) 208 .opacity(0.9) 209 Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6) 210 }.width('100%').padding({ left: 12, right: 12 }).height(56) 211 } 212 213 build() { 214 Column() { 215 // 红点类型的标记组件 216 Text('dotsBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 217 Tabs() { 218 TabContent() 219 .tabBar(this.tabBuilder(0)) 220 TabContent() 221 .tabBar(this.tabBuilder(1)) 222 TabContent() 223 .tabBar(this.tabBuilder(2)) 224 TabContent() 225 .tabBar(this.tabBuilder(3)) 226 } 227 .width(360) 228 .height(56) 229 .backgroundColor('#F1F3F5') 230 231 // 根据字符创建的标记组件 232 Column() { 233 Text('stringBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 234 List({ space: 12 }) { 235 ListItem() { 236 Text('list1').fontSize(14).fontColor('#182431').margin({ left: 12 }) 237 } 238 .width('100%') 239 .height(56) 240 .backgroundColor('#FFFFFF') 241 .borderRadius(24) 242 .align(Alignment.Start) 243 244 ListItem() { 245 Badge({ 246 value: 'New', 247 position: BadgePosition.Right, 248 style: { badgeSize: 16, badgeColor: '#FA2A2D' } 249 }) { 250 Text('list2').width(27).height(19).fontSize(14).fontColor('#182431') 251 }.width(49.5).height(19) 252 .margin({ left: 12 }) 253 } 254 .width('100%') 255 .height(56) 256 .backgroundColor('#FFFFFF') 257 .borderRadius(24) 258 .align(Alignment.Start) 259 }.width(336) 260 261 // 根据数字创建的标记组件 262 Text('numberBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 263 List() { 264 ListItem() { 265 this.itemBuilder('list1') 266 } 267 268 ListItem() { 269 Row() { 270 Image('common/public_icon.svg').width(32).height(32).opacity(0.6) 271 Badge({ 272 count: 1, 273 position: BadgePosition.Right, 274 style: { badgeSize: 16, badgeColor: '#FA2A2D' } 275 }) { 276 Text('list2') 277 .width(177) 278 .height(21) 279 .textAlign(TextAlign.Start) 280 .fontColor('#182431') 281 .fontWeight(500) 282 .fontSize(16) 283 .opacity(0.9) 284 }.width(240).height(21).margin({ left: 15, right: 11 }) 285 286 Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6) 287 }.width('100%').padding({ left: 12, right: 12 }).height(56) 288 } 289 290 ListItem() { 291 this.itemBuilder('list3') 292 } 293 294 ListItem() { 295 this.itemBuilder('list4') 296 } 297 } 298 .width(336) 299 .height(232) 300 .backgroundColor('#FFFFFF') 301 .borderRadius(24) 302 .padding({ top: 4, bottom: 4 }) 303 .divider({ 304 strokeWidth: 0.5, 305 color: 'rgba(0,0,0,0.1)', 306 startMargin: 60, 307 endMargin: 12 308 }) 309 }.width('100%').backgroundColor('#F1F3F5').padding({ bottom: 12 }) 310 }.width('100%') 311 } 312} 313``` 314 315 316 317### 示例2（设置数字控制标记显隐） 318 319该示例通过count属性，实现了设置数字0和1时标记组件的隐藏和显示效果。 320 321```ts 322// 该示例实现了Badge组件显隐时缩放 323@Entry 324@Component 325struct Index { 326 @State badgeCount: number = 1; 327 328 build() { 329 Column({ space: 40 }) { 330 Badge({ 331 count: this.badgeCount, 332 style: {}, 333 position: BadgePosition.RightTop, 334 }) { 335 Image($r("app.media.startIcon")) 336 .width(50) 337 .height(50) 338 } 339 .width(55) 340 341 Button('count 0').onClick(() => { 342 this.badgeCount = 0; 343 }) 344 Button('count 1').onClick(() => { 345 this.badgeCount = 1; 346 }) 347 } 348 .margin({ top: 20 }) 349 } 350} 351``` 352 353 354
