1# DataPanel 2 3The **DataPanel** component is used to display proportions in a chart. 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 12Not supported 13 14 15## APIs 16 17DataPanel(options: DataPanelOptions) 18 19**Widget capability**: This API can be used in ArkTS widgets since API version 9. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.ArkUI.ArkUI.Full 24 25**Parameters** 26 27| Name| Type| Mandatory| Description| 28| -------- | -------- | -------- | -------- | 29| options | [DataPanelOptions](#datapaneloptions)| Yes| Parameters of the data panel.| 30 31## DataPanelOptions 32 33**Widget capability**: This API can be used in ArkTS widgets since API version 9. 34 35**Atomic service API**: This API can be used in atomic services since API version 11. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39| Name | Type | Mandatory | Description| 40| ----------------- | -------- | ----- | -------- | 41| values | number[] | Yes | Data value list. A maximum of nine values are supported. If more than nine values are set, only the first nine ones are used. A value less than 0 evaluates to the value **0**.| 42| max | number | No | - When set to a value greater than 0, this parameter indicates the maximum value in the **values** list.<br>- When set to a value equal to or smaller than 0, this parameter indicates the sum of values in the **values** list. The values are displayed in proportion.<br>Default value: **100**| 43| type<sup>8+</sup> | [DataPanelType](#datapaneltype8) | No| Type of the data panel (dynamic modification is not supported).<br>Default value: **DataPanelType.Circle**| 44 45 46## DataPanelType<sup>8+</sup> 47 48**Widget capability**: This API can be used in ArkTS widgets since API version 9. 49 50**Atomic service API**: This API can be used in atomic services since API version 11. 51 52**System capability**: SystemCapability.ArkUI.ArkUI.Full 53 54| Name| Description| 55| -------| ------------ | 56| Line | Line data panel.| 57| Circle | Circle data panel.| 58 59 60## Attributes 61 62In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 63 64### closeEffect 65 66closeEffect(value: boolean) 67 68Sets whether to disable the rotation and shadow effects for the component. This attribute enables or disables the shadow effect only when [trackShadow](#trackshadow10) is not set. The shadow effect enabled through this attribute is in the default style. 69 70**Widget capability**: This API can be used in ArkTS widgets since API version 9. 71 72**Atomic service API**: This API can be used in atomic services since API version 11. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------- | ---- | ------------------------------------------------------ | 80| value | boolean | Yes | Whether to disable the rotation and shadow effects for the component.<br>Default value: **false**<br>**false**: Disable the rotation and shadow effects.<b>**true**: Enable the rotation and shadow effects.| 81 82### valueColors<sup>10+</sup> 83 84valueColors(value: Array<ResourceColor | LinearGradient>) 85 86Sets an array of data segment colors. 87 88**Atomic service API**: This API can be used in atomic services since API version 11. 89 90**System capability**: SystemCapability.ArkUI.ArkUI.Full 91 92**Parameters** 93 94| Name| Type | Mandatory| Description | 95| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 96| value | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | Yes | Array of data segment colors. A value of the **ResourceColor** type indicates a solid color, and A value of the **LinearGradient** type indicates a color gradient.| 97 98### trackBackgroundColor<sup>10+</sup> 99 100trackBackgroundColor(value: ResourceColor) 101 102Sets the background color. 103 104**Atomic service API**: This API can be used in atomic services since API version 11. 105 106**System capability**: SystemCapability.ArkUI.ArkUI.Full 107 108**Parameters** 109 110| Name| Type | Mandatory| Description | 111| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 112| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color.<br>The value is in hexadecimal ARGB notation. The first two digits indicate opacity.<br>Default value: **'#08182431'**| 113 114### strokeWidth<sup>10+</sup> 115 116strokeWidth(value: Length) 117 118Sets the stroke width of the border. This attribute does not take effect when the data panel type is **DataPanelType.Line**. 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**Parameters** 125 126| Name| Type | Mandatory| Description | 127| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 128| value | [Length](ts-types.md#length) | Yes | Stroke width of the border.<br>Default value: **24**<br>Unit: vp<br>**NOTE**<br>If a value less than 0 is set, the default value is used.<br>If the value exceeds the radius of the ring, the thickness will automatically be adjusted to 12% of the ring's radius to prevent visual issues. Excessively large values may cause the ring to disappear.| 129 130### trackShadow<sup>10+</sup> 131 132trackShadow(value: DataPanelShadowOptions) 133 134Sets the shadow style. 135 136**Atomic service API**: This API can be used in atomic services since API version 11. 137 138**System capability**: SystemCapability.ArkUI.ArkUI.Full 139 140**Parameters** 141 142| Name| Type | Mandatory| Description | 143| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 144| value | [DataPanelShadowOptions](#datapanelshadowoptions10) | Yes | Shadow style.<br>**NOTE**<br>If this attribute is set to **null**, the shadow effect is disabled.| 145 146### contentModifier<sup>12+</sup> 147 148contentModifier(modifier: ContentModifier\<DataPanelConfiguration>) 149 150Creates a content modifier. 151 152**Atomic service API**: This API can be used in atomic services since API version 12. 153 154**System capability**: SystemCapability.ArkUI.ArkUI.Full 155 156**Parameters** 157 158| Name| Type | Mandatory| Description | 159| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 160| modifier | [ContentModifier\<DataPanelConfiguration>](#datapanelconfiguration12) | Yes | Content modifier to apply to the current component.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.| 161 162 163## DataPanelShadowOptions<sup>10+</sup> 164 165Inherits from [MultiShadowOptions](ts-types.md#multishadowoptions10) and has all attributes of **MultiShadowOptions**. 166 167**Atomic service API**: This API can be used in atomic services since API version 11. 168 169**System capability**: SystemCapability.ArkUI.ArkUI.Full 170 171| Name | Type| Mandatory| Description| 172| ------------- | ------- | ---- | -------- | 173| colors | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | No| Array of shadow colors for data segments.<br>Default value: same as the value of **valueColors**<br>**NOTE**<br>If the number of the set shadow colors is less than that of the data segments, the number of the displayed shadow colors is the same as the former.<br>If the number of the set shadow colors is greater than that of the data segments, the number of the displayed shadow colors is the same as the latter.| 174 175## LinearGradient<sup>10+</sup> 176 177### constructor 178 179constructor(colorStops: ColorStop[]) 180 181Describes the linear gradient. 182 183**Atomic service API**: This API can be used in atomic services since API version 11. 184 185**System capability**: SystemCapability.ArkUI.ArkUI.Full 186 187**Parameters** 188 189| Name | Type| Mandatory| Description| 190| ------------- | ------- | ---- | -------- | 191| colorStops | [ColorStop](#colorstop10)[] | Yes| Gradient colors and color stops.| 192 193 194## ColorStop<sup>10+</sup> 195 196Describes the gradient color stop. 197 198**Atomic service API**: This API can be used in atomic services since API version 11. 199 200**System capability**: SystemCapability.ArkUI.ArkUI.Full 201 202| Name | Type| Mandatory| Description| 203| ------------- | ------- | ---- | -------- | 204| color | [ResourceColor](ts-types.md#resourcecolor) | Yes| Color value.| 205| offset | [Length](ts-types.md#length) | Yes| Gradient color stop (proportion value between 0 and 1). A value less than 0 evaluates to the value **0**. A value greater than 1 evaluates to the value **1**.<br>**NOTE**<br>If the value is a string that represents a number, it will be converted to a number.<br>For example, **'10vp'** is converted to 10, and **'10%'** is converted to 0.1.| 206 207## DataPanelConfiguration<sup>12+</sup> 208 209You need a custom class to implement the **ContentModifier** API. 210 211**Atomic service API**: This API can be used in atomic services since API version 12. 212 213**System capability**: SystemCapability.ArkUI.ArkUI.Full 214 215| Name | Type | Mandatory | Description | 216| ------ | ------ | ------ |-------------------------------- | 217| values | number[] | Yes| Current values of the data panel.<br>Value range: [0, 9]<br>Values less than 0 are adjusted to **0**.| 218| maxValue | number | Yes| Maximum value displayed in the data panel.<br>Default value: **100**<br>**NOTE**<br>If the value is less than or equal to 0, **maxValue** is set to the sum of all items in the **values** array and displayed proportionally.| 219 220## Example 221 222### Example 1: Setting Data Panel Types 223 224This example demonstrates how to set different types of data panels using the **type** attribute. 225 226```ts 227// xxx.ets 228@Entry 229@Component 230struct DataPanelExample { 231 public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10] 232 233 build() { 234 Column({ space: 5 }) { 235 Row() { 236 Stack() { 237 // Single-segment circular data panel 238 DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168) 239 Column() { 240 Text('30').fontSize(35).fontColor('#182431') 241 Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6) 242 } 243 244 Text('%') 245 .fontSize(9.33) 246 .lineHeight(12.83) 247 .fontWeight(500) 248 .opacity(0.6) 249 .position({ x: 104.42, y: 78.17 }) 250 }.margin({ right: 44 }) 251 252 // Multi-segment circular data panel 253 Stack() { 254 DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168) 255 Column() { 256 Text('75').fontSize(35).fontColor('#182431') 257 Text('Used: 98 GB/128 GB') .fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6) 258 } 259 260 Text('%') 261 .fontSize(9.33) 262 .lineHeight(12.83) 263 .fontWeight(500) 264 .opacity(0.6) 265 .position({ x: 104.42, y: 78.17 }) 266 } 267 }.margin({ bottom: 59 }) 268 269 // Linear data panel 270 DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20) 271 }.width('100%').margin({ top: 5 }) 272 } 273} 274``` 275 276 277 278### Example 2: Setting Gradient Colors and Shadows 279 280This example demonstrates how to set gradient colors and shadows using the **valueColors** and **trackShadow** attributes. 281 282```ts 283// xxx.ets 284@Entry 285@Component 286struct LinearGradientDataPanelExample { 287 public values1: number[] = [20, 20, 20, 20] 288 public color1: LinearGradient = 289 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }]) 290 public color2: LinearGradient = 291 new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }]) 292 public colorShadow1: LinearGradient = 293 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }]) 294 public colorShadow2: LinearGradient = 295 new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }]) 296 public colorShadow3: LinearGradient = 297 new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }]) 298 public colorShadow4: LinearGradient = 299 new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }]) 300 @State color3: string = '#00FF00' 301 @State color4: string = '#20FF0000' 302 @State bgColor: string = '#08182431' 303 @State offsetX: number = 15 304 @State offsetY: number = 15 305 @State radius: number = 5 306 @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4] 307 @State shadowColorArray: Array<LinearGradient | ResourceColor> = 308 [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4] 309 310 build() { 311 Column({ space: 5 }) { 312 Text('LinearGradient') 313 .fontSize(9) 314 .fontColor(0xCCCCCC) 315 .textAlign(TextAlign.Start) 316 .width('100%') 317 .margin({ top: 20, left: 20 }) 318 DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle }) 319 .width(300) 320 .height(300) 321 .valueColors(this.colorArray) 322 .trackShadow({ 323 radius: this.radius, 324 colors: this.shadowColorArray, 325 offsetX: this.offsetX, 326 offsetY: this.offsetY 327 }) 328 .strokeWidth(30) 329 .trackBackgroundColor(this.bgColor) 330 }.width('100%').margin({ top: 5 }) 331 } 332} 333``` 334 335 336 337### Example 3: Disabling Animations and Shadows 338 339This example demonstrates how to disable animations and shadows using the **closeEffect** attribute. 340 341```ts 342// xxx.ets 343@Entry 344@Component 345struct LinearGradientDataPanelExample { 346 public values1: number[] = [20, 20, 20, 20] 347 public color1: LinearGradient = 348 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }]) 349 public color2: LinearGradient = 350 new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }]) 351 public colorShadow1: LinearGradient = 352 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }]) 353 public colorShadow2: LinearGradient = 354 new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }]) 355 public colorShadow3: LinearGradient = 356 new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }]) 357 public colorShadow4: LinearGradient = 358 new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }]) 359 @State color3: string = '#00FF00' 360 @State color4: string = '#20FF0000' 361 @State bgColor: string = '#08182431' 362 @State offsetX: number = 15 363 @State offsetY: number = 15 364 @State radius: number = 5 365 @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4] 366 @State shadowColorArray: Array<LinearGradient | ResourceColor> = 367 [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4] 368 369 build() { 370 Column({ space: 5 }) { 371 Text('LinearGradient') 372 .fontSize(9) 373 .fontColor(0xCCCCCC) 374 .textAlign(TextAlign.Start) 375 .width('100%') 376 .margin({ top: 20, left: 20 }) 377 DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle }) 378 .width(300) 379 .height(300) 380 .valueColors(this.colorArray) 381 .strokeWidth(30) 382 .closeEffect(true) 383 .trackBackgroundColor(this.bgColor) 384 }.width('100%').margin({ top: 5 }) 385 } 386} 387``` 388 389 390 391### Example 4: Setting the Custom Content Area 392 393This example shows how to customize the content area of the data panel using the **contentModifier** attribute. 394 395```ts 396// xxx.ets 397@Builder 398function buildDataPanel(config: DataPanelConfiguration) { 399 Column() { 400 Column() { 401 ForEach(config.values, (item: number, index: number) => { 402 ChildItem({ item: item, index: index, max: config.maxValue }) 403 }, (item: string) => item) 404 }.padding(10) 405 406 Column() { 407 Line().width("100%").backgroundColor("#ff373737").margin({ bottom: 5 }) 408 }.padding({ left: 20, right: 20 }) 409 410 Row() { 411 Text('Length=' + config.values.length + ' ').margin({ left: 10 }).align(Alignment.Start) 412 Text('Max=' + config.maxValue).margin({ left: 10 }).align(Alignment.Start) 413 } 414 } 415} 416 417class DataPanelBuilder implements ContentModifier<DataPanelConfiguration> { 418 constructor() { 419 } 420 421 applyContent(): WrappedBuilder<[DataPanelConfiguration]> { 422 return wrapBuilder(buildDataPanel) 423 } 424} 425 426@Entry 427@Component 428struct Index { 429 build() { 430 Column() { 431 Text("Data panel").margin({ top: 12 }); 432 Row() { 433 DataPanel({ values: [12.3, 21.1, 13.4, 35.2, 26.0, 32.0], max: 140, type: DataPanelType.Circle }) 434 .width(400) 435 .height(260) 436 .constraintSize({ maxWidth: "100%" }) 437 .padding({ top: 10 }) 438 .contentModifier(new DataPanelBuilder()) 439 }.margin(15).backgroundColor("#fff5f5f5") 440 } 441 } 442} 443 444@Component 445struct ChildItem { 446 @Prop item: number; 447 @Prop index: number; 448 @Prop max: number; 449 public color1: string = "#65ff00dd" 450 public color2: string = "#6500ff99" 451 public color3: string = "#65ffe600" 452 public color4: string = "#6595ff00" 453 public color5: string = "#65000dff" 454 public color6: string = "#650099ff" 455 public colorArray: Array<string> = [this.color1, this.color2, this.color3, this.color4, this.color5, this.color6] 456 457 build() { 458 RelativeContainer() { 459 Row() { 460 Rect() 461 .height(25) 462 .width(this.item * 600 / this.max) 463 .foregroundColor(this.colorArray[this.index]) 464 .radius(5) 465 .align(Alignment.Start) 466 Text(" " + this.item) 467 .fontSize(17) 468 } 469 }.height(28) 470 } 471} 472``` 473 474
