1# Badge 2 3The **Badge** component is a container that can be attached to another component for notification and reminder purposes. 4 5> **NOTE** 6> 7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Child Components 11 12This component supports only one child component. 13 14> **NOTE** 15> 16> Supported types of child components: built-in components and custom components, with support for ([if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control. 17 18 19## APIs 20 21### Badge 22 23Badge(value: BadgeParamWithNumber) 24 25Creates a badge with the given numerical value. 26 27**Widget capability**: This API can be used in ArkTS widgets since API version 9. 28 29**Atomic service API**: This API can be used in atomic services since API version 11. 30 31**System capability**: SystemCapability.ArkUI.ArkUI.Full 32 33**Parameters** 34 35| Name| Type| Mandatory| Description| 36| -------- | -------- | -------- | -------- | 37| value | [BadgeParamWithNumber](#badgeparamwithnumber)| Yes| Options of the numeric badge.| 38 39### Badge 40 41Badge(value: BadgeParamWithString) 42 43Creates a badge with the given string. 44 45**Widget capability**: This API can be used in ArkTS widgets since API version 9. 46 47**Atomic service API**: This API can be used in atomic services since API version 11. 48 49**System capability**: SystemCapability.ArkUI.ArkUI.Full 50 51This component supports the scaling effect for visibility transition since API version 12. 52 53**Parameters** 54 55| Name| Type | Mandatory| Description | 56| ------ | ----------------------------------------------------- | ---- | -------------------- | 57| value | [BadgeParamWithString](#badgeparamwithstring) | Yes | Options of the string-type badge.| 58 59## BadgeParam 60 61Provides basic parameters for creating a badge. 62 63**Widget capability**: This API can be used in ArkTS widgets since API version 9. 64 65**Atomic service API**: This API can be used in atomic services since API version 11. 66 67**System capability**: SystemCapability.ArkUI.ArkUI.Full 68 69| Name| Type| Mandatory| Description| 70| -------- | -------- | -------- | -------- | 71| position | [BadgePosition](#badgeposition)\|[Position<sup>10+</sup>](ts-types.md#position) | No| Position to display the badge relative to the parent component.<br>Default value: **BadgePosition.RightTop**<br>**NOTE**<br> This parameter cannot be set in percentage. If it is set to an invalid value, the default value **(0,0)** which indicates the upper left corner of the component, will be used.| 72| style | [BadgeStyle](#badgestyle) | Yes| Style of the badge, including the font color, font size, badge color, and badge size.| 73 74 75## BadgeParamWithNumber 76 77Inherits from [BadgeParam](#badgeparam) and has all attributes of **BadgeParam**. 78 79**Widget capability**: This API can be used in ArkTS widgets since API version 9. 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83**System capability**: SystemCapability.ArkUI.ArkUI.Full 84 85| Name| Type| Mandatory| Description| 86| -------- | -------- | -------- | -------- | 87| count | number | Yes| Number of notifications.<br>**NOTE**<br>If the value is less than or equal to 0, no badge is displayed.<br>Value range: [-2147483648, 2147483647]<br>If the value is out of the range, 4294967296 is added or subtracted so that the value is within the range. If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.| 88| maxCount | number | No| Maximum number of notifications. When the maximum number is reached, only **maxCount+** is displayed.<br>Default value: **99**<br>Value range: [-2147483648, 2147483647]<br>If the value is out of the range, 4294967296 is added or subtracted so that the value is within the range. If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.| 89 90## BadgeParamWithString 91 92Inherits from [BadgeParam](#badgeparam) and has all attributes of **BadgeParam**. 93 94**Widget capability**: This API can be used in ArkTS widgets since API version 9. 95 96**Atomic service API**: This API can be used in atomic services since API version 11. 97 98**System capability**: SystemCapability.ArkUI.ArkUI.Full 99 100| Name| Type| Mandatory| Description| 101| -------- | -------- | -------- | -------- | 102| value | string | Yes| Prompt content.| 103 104## BadgePosition 105 106**Widget capability**: This API can be used in ArkTS widgets since API version 9. 107 108**Atomic service API**: This API can be used in atomic services since API version 11. 109 110**System capability**: SystemCapability.ArkUI.ArkUI.Full 111 112| Name| Value| Description| 113| -------- | -------- |-------- | 114| RightTop | 0 | The badge is displayed in the upper right corner of the parent component.| 115| Right | 1 | The badge is vertically centered on the right of the parent component.| 116| Left | 2 | The badge is vertically centered on the left of the parent component.| 117 118## BadgeStyle 119 120**Atomic service API**: This API can be used in atomic services since API version 11. 121 122**System capability**: SystemCapability.ArkUI.ArkUI.Full 123 124| Name | Type | Mandatory| Description | 125| ------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 126| color | [ResourceColor](ts-types.md#resourcecolor) | No | Font color.<br>Default value: **Color.White**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 127| fontSize | number \| string | No | Font size.<br>Default value: **10**<br>Unit: fp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 128| badgeSize | number \| string | No | Badge size.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 129| badgeColor | [ResourceColor](ts-types.md#resourcecolor) | No | Badge color.<br>Default value: **Color.Red**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.| 130| fontWeight<sup>10+</sup> | number \|[FontWeight](ts-appendix-enums.md#fontweight) \| string | No | Font weight of the text.<br>Default value: **FontWeight.Normal**<br>**NOTE**<br>This parameter cannot be set in percentage.| 131| borderColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor) | No | Border color of the background.<br>Default value: **Color.Red** | 132| borderWidth<sup>10+</sup> | [Length](ts-types.md#length) | No | Border width of the background.<br>Default value: **1**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.| 133 134## Attributes 135 136The [universal attributes](ts-universal-attributes-size.md) are supported. 137 138## Events 139 140The [universal events](ts-universal-events-click.md) are supported. 141 142## Example 143 144### Example 1: Setting the Badge Content 145 146This example illustrates the varying visual effects of the **Badge** component when it receives empty values, character strings, and numerical values through the **value** and **count** properties. 147 148```ts 149// xxx.ets 150@Entry 151@Component 152struct BadgeExample { 153 @Builder tabBuilder(index: number) { 154 Column() { 155 if (index === 2) { 156 Badge({ 157 value: '', 158 style: { badgeSize: 6, badgeColor: '#FA2A2D' } 159 }) { 160 Image('/common/public_icon_off.svg') 161 .width(24) 162 .height(24) 163 } 164 .width(24) 165 .height(24) 166 .margin({ bottom: 4 }) 167 } else { 168 Image('/common/public_icon_off.svg') 169 .width(24) 170 .height(24) 171 .margin({ bottom: 4 }) 172 } 173 Text('Tab') 174 .fontColor('#182431') 175 .fontSize(10) 176 .fontWeight(500) 177 .lineHeight(14) 178 }.width('100%').height('100%').justifyContent(FlexAlign.Center) 179 } 180 181 @Builder itemBuilder(value: string) { 182 Row() { 183 Image('common/public_icon.svg').width(32).height(32).opacity(0.6) 184 Text(value) 185 .width(177) 186 .height(21) 187 .margin({ left: 15, right: 76 }) 188 .textAlign(TextAlign.Start) 189 .fontColor('#182431') 190 .fontWeight(500) 191 .fontSize(16) 192 .opacity(0.9) 193 Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6) 194 }.width('100%').padding({ left: 12, right: 12 }).height(56) 195 } 196 197 build() { 198 Column() { 199 // Badge of the red dot type 200 Text('dotsBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 201 Tabs() { 202 TabContent() 203 .tabBar(this.tabBuilder(0)) 204 TabContent() 205 .tabBar(this.tabBuilder(1)) 206 TabContent() 207 .tabBar(this.tabBuilder(2)) 208 TabContent() 209 .tabBar(this.tabBuilder(3)) 210 } 211 .width(360) 212 .height(56) 213 .backgroundColor('#F1F3F5') 214 215 // Create a badge with the given string. 216 Column() { 217 Text('stringBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 218 List({ space: 12 }) { 219 ListItem() { 220 Text('list1').fontSize(14).fontColor('#182431').margin({ left: 12 }) 221 } 222 .width('100%') 223 .height(56) 224 .backgroundColor('#FFFFFF') 225 .borderRadius(24) 226 .align(Alignment.Start) 227 228 ListItem() { 229 Badge({ 230 value: 'New', 231 position: BadgePosition.Right, 232 style: { badgeSize: 16, badgeColor: '#FA2A2D' } 233 }) { 234 Text('list2').width(27).height(19).fontSize(14).fontColor('#182431') 235 }.width(49.5).height(19) 236 .margin({ left: 12 }) 237 } 238 .width('100%') 239 .height(56) 240 .backgroundColor('#FFFFFF') 241 .borderRadius(24) 242 .align(Alignment.Start) 243 }.width(336) 244 245 // Create a badge with the given numerical value. 246 Text('numberBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24) 247 List() { 248 ListItem() { 249 this.itemBuilder('list1') 250 } 251 252 ListItem() { 253 Row() { 254 Image('common/public_icon.svg').width(32).height(32).opacity(0.6) 255 Badge({ 256 count: 1, 257 position: BadgePosition.Right, 258 style: { badgeSize: 16, badgeColor: '#FA2A2D' } 259 }) { 260 Text('list2') 261 .width(177) 262 .height(21) 263 .textAlign(TextAlign.Start) 264 .fontColor('#182431') 265 .fontWeight(500) 266 .fontSize(16) 267 .opacity(0.9) 268 }.width(240).height(21).margin({ left: 15, right: 11 }) 269 270 Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6) 271 }.width('100%').padding({ left: 12, right: 12 }).height(56) 272 } 273 274 ListItem() { 275 this.itemBuilder('list3') 276 } 277 278 ListItem() { 279 this.itemBuilder('list4') 280 } 281 } 282 .width(336) 283 .height(232) 284 .backgroundColor('#FFFFFF') 285 .borderRadius(24) 286 .padding({ top: 4, bottom: 4 }) 287 .divider({ strokeWidth: 0.5, color: 'rgba(0,0,0,0.1)', startMargin: 60, endMargin: 12 }) 288 }.width('100%').backgroundColor('#F1F3F5').padding({ bottom: 12 }) 289 }.width('100%') 290 } 291} 292``` 293 294 295 296### Example 2: Controlling the Badge Visibility with Numbers 297 298This example shows how to use the **count** property to toggle the visibility of the **Badge** component. Specifically, when the **count** property is set to **0**, the badge is hidden; when it is set to **1**, the badge becomes visible. 299 300```ts 301// This example implements scaling when the badge visibility changes. 302@Entry 303@Component 304struct Index { 305 @State badgeCount: number = 1 306 307 build() { 308 Column({ space: 40 }) { 309 Badge({ 310 count: this.badgeCount, 311 style: {}, 312 position: BadgePosition.RightTop, 313 }) { 314 Image($r("app.media.icon")) 315 .width(50) 316 .height(50) 317 } 318 .width(55) 319 Button('count 0').onClick(() => { 320 this.badgeCount = 0 321 }) 322 Button('count 1').onClick(() => { 323 this.badgeCount = 1 324 }) 325 } 326 .margin({top: 20}) 327 } 328} 329``` 330 331 332
