1# DataPanel 2 3The **DataPanel** component displays 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 11 12## Child Components 13 14Not supported 15 16 17## APIs 18 19DataPanel(options: DataPanelOptions) 20 21**Widget capability**: This API can be used in ArkTS widgets since API version 9. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 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**Atomic service API**: This API can be used in atomic services since API version 11. 34 35| Name | Type | Mandatory | Description| 36| ----------------- | -------- | ----- | -------- | 37| 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**.| 38| 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**| 39| type<sup>8+</sup> | [DataPanelType](#datapaneltype8) | No| Type of the data panel (dynamic modification is not supported).<br>Default value: **DataPanelType.Circle**| 40 41 42## DataPanelType<sup>8+</sup> 43 44This API can be used in ArkTS widgets since API version 9. 45 46**Atomic service API**: This API can be used in atomic services since API version 11. 47 48| Name| Description| 49| -------| ------------ | 50| Line | Line data panel.| 51| Circle | Circle data panel.| 52 53 54## Attributes 55 56In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 57 58### closeEffect 59 60closeEffect(value: boolean) 61 62Sets 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. 63 64**Widget capability**: This API can be used in ArkTS widgets since API version 9. 65 66**Atomic service API**: This API can be used in atomic services since API version 11. 67 68**System capability**: SystemCapability.ArkUI.ArkUI.Full 69 70**Parameters** 71 72| Name| Type | Mandatory| Description | 73| ------ | ------- | ---- | ------------------------------------------------------ | 74| value | boolean | Yes | Whether to disable the rotation and shadow effects for the component.<br>Default value: **false**| 75 76### valueColors<sup>10+</sup> 77 78valueColors(value: Array<ResourceColor | LinearGradient>) 79 80Sets an array of data segment colors. 81 82**Atomic service API**: This API can be used in atomic services since API version 11. 83 84**System capability**: SystemCapability.ArkUI.ArkUI.Full 85 86**Parameters** 87 88| Name| Type | Mandatory| Description | 89| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 90| 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.| 91 92### trackBackgroundColor<sup>10+</sup> 93 94trackBackgroundColor(value: ResourceColor) 95 96Sets the background color. 97 98**Atomic service API**: This API can be used in atomic services since API version 11. 99 100**System capability**: SystemCapability.ArkUI.ArkUI.Full 101 102**Parameters** 103 104| Name| Type | Mandatory| Description | 105| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 106| 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'**| 107 108### strokeWidth<sup>10+</sup> 109 110strokeWidth(value: Length) 111 112Sets the stroke width of the border. This attribute does not take effect when the data panel type is **DataPanelType.Line**. 113 114**Atomic service API**: This API can be used in atomic services since API version 11. 115 116**System capability**: SystemCapability.ArkUI.ArkUI.Full 117 118**Parameters** 119 120| Name| Type | Mandatory| Description | 121| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 122| value | [Length](ts-types.md#length) | Yes | Stroke width of the border.<br>Default value: **24**<br>Unit: vp<br>**NOTE**<br>A value less than 0 evaluates to the default value.| 123 124### trackShadow<sup>10+</sup> 125 126trackShadow(value: DataPanelShadowOptions) 127 128Sets the shadow style. 129 130**Atomic service API**: This API can be used in atomic services since API version 11. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 138| value | [DataPanelShadowOptions](#datapanelshadowoptions10) | Yes | Shadow style.<br>**NOTE**<br>If this attribute is set to **null**, the shadow effect is disabled.| 139 140### contentModifier<sup>12+</sup> 141 142contentModifier(modifier: ContentModifier\<DataPanelConfiguration>) 143 144Creates a content modifier. 145 146**System capability**: SystemCapability.ArkUI.ArkUI.Full 147 148**Parameters** 149 150| Name| Type | Mandatory| Description | 151| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 152| 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.| 153 154 155## DataPanelShadowOptions<sup>10+</sup> 156 157Inherits from [MultiShadowOptions](ts-types.md#multishadowoptions10) and has all attributes of **MultiShadowOptions**. 158 159**Atomic service API**: This API can be used in atomic services since API version 11. 160 161| Name | Type| Mandatory| Description| 162| ------------- | ------- | ---- | -------- | 163| 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.| 164 165## LinearGradient<sup>10+</sup> 166 167Describes the linear gradient. 168 169LinearGradient(colorStops: ColorStop[]) 170 171**Atomic service API**: This API can be used in atomic services since API version 11. 172 173| Name | Type| Mandatory| Description| 174| ------------- | ------- | ---- | -------- | 175| colorStops | [ColorStop](#colorstop10)[] | Yes| Gradient colors and color stops.| 176 177 178## ColorStop<sup>10+</sup> 179 180Describes the gradient color stop. 181 182**Atomic service API**: This API can be used in atomic services since API version 11. 183 184| Name | Type| Mandatory| Description| 185| ------------- | ------- | ---- | -------- | 186| color | [ResourceColor](ts-types.md#resourcecolor) | Yes| Color value.| 187| 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.| 188 189## DataPanelConfiguration<sup>12+</sup> 190 191You need a custom class to implement the **ContentModifier** API. 192 193| Name | Type | Default Value | Description | 194| ------ | ------ | ------ |-------------------------------- | 195| values | number[] | - | Current values of the data panel. The maximum length is 9.| 196| maxValue | number | 100 | Maximum value displayed in the data panel.| 197 198## Example 199 200### Example 1 201 202```ts 203// xxx.ets 204@Entry 205@Component 206struct DataPanelExample { 207 public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10] 208 209 build() { 210 Column({ space: 5 }) { 211 Row() { 212 Stack() { 213 DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168) 214 Column() { 215 Text('30').fontSize(35).fontColor('#182431') 216 Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6) 217 } 218 219 Text('%') 220 .fontSize(9.33) 221 .lineHeight(12.83) 222 .fontWeight(500) 223 .opacity(0.6) 224 .position({ x: 104.42, y: 78.17 }) 225 }.margin({ right: 44 }) 226 227 Stack() { 228 DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168) 229 Column() { 230 Text('75').fontSize(35).fontColor('#182431') 231 Text('Used: 98 GB/128 GB') .fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6) 232 } 233 234 Text('%') 235 .fontSize(9.33) 236 .lineHeight(12.83) 237 .fontWeight(500) 238 .opacity(0.6) 239 .position({ x: 104.42, y: 78.17 }) 240 } 241 }.margin({ bottom: 59 }) 242 243 DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20) 244 }.width('100%').margin({ top: 5 }) 245 } 246} 247``` 248 249 250 251### Example 2 252 253```ts 254// xxx.ets 255@Entry 256@Component 257struct LinearGradientDataPanelExample { 258 public values1: number[] = [20, 20, 20, 20] 259 public color1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }]) 260 public color2: LinearGradient = new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }]) 261 public colorShadow1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }]) 262 public colorShadow2: LinearGradient = new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }]) 263 public colorShadow3: LinearGradient = new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }]) 264 public colorShadow4: LinearGradient = new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }]) 265 @State color3: string = '#00FF00' 266 @State color4: string = '#20FF0000' 267 @State bgColor: string = '#08182431' 268 @State offsetX: number = 15 269 @State offsetY: number = 15 270 @State radius: number = 5 271 @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4] 272 @State shadowColorArray: Array<LinearGradient | ResourceColor> = [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4] 273 274 build() { 275 Column({ space: 5 }) { 276 Text('LinearGradient').fontSize(9).fontColor(0xCCCCCC).textAlign(TextAlign.Start).width('100%').margin({ top: 20, left: 20}) 277 DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle }) 278 .width(300) 279 .height(300) 280 .valueColors(this.colorArray) 281 .trackShadow({ 282 radius: this.radius, 283 colors: this.shadowColorArray, 284 offsetX: this.offsetX, 285 offsetY: this.offsetY 286 }) 287 .strokeWidth(30) 288 .trackBackgroundColor(this.bgColor) 289 }.width('100%').margin({ top: 5 }) 290 } 291} 292``` 293 294 295 296### Example 3 297 298```ts 299// xxx.ets 300@Builder 301function buildDataPanel(config: DataPanelConfiguration) { 302 Column() { 303 Column() { 304 ForEach(config.values, (item: number, index: number) => { 305 ChildItem({ item: item, index: index, max:config.maxValue}) 306 }, (item: string) => item) 307 }.padding(10) 308 Line().width(360).backgroundColor("#ff373737").margin({bottom:5}) 309 Row() { 310 Text('Length=' + config.values.length + ' ').margin({ left: 10 }).align(Alignment.Start) 311 Text('Max=' + config.maxValue).margin({ left: 10 }).align(Alignment.Start) 312 } 313 } 314} 315 316class DataPanelBuilder implements ContentModifier<DataPanelConfiguration> { 317 constructor() { 318 } 319 applyContent () : WrappedBuilder<[DataPanelConfiguration]> { 320 return wrapBuilder(buildDataPanel) 321 } 322} 323 324@Entry 325@Component 326struct Index { 327 build() { 328 Column() { 329 Text("Data panel").margin({ top: 12 }); 330 Row() { 331 DataPanel({ values: [12.3, 21.1, 13.4, 35.2, 26.0, 32.0], max: 140, type: DataPanelType.Circle }) 332 .width(400).height(260) 333 .padding({ top: 10 }) 334 .contentModifier(new DataPanelBuilder()) 335 }.margin(15).backgroundColor("#fff5f5f5") 336 } 337 } 338} 339 340@Component 341struct ChildItem { 342 @Prop item: number; 343 @Prop index: number; 344 @Prop max: number; 345 public color1: string = "#65ff00dd" 346 public color2: string = "#6500ff99" 347 public color3: string = "#65ffe600" 348 public color4: string = "#6595ff00" 349 public color5: string = "#65000dff" 350 public color6: string = "#650099ff" 351 public colorArray: Array<string> = [this.color1, this.color2, this.color3, this.color4, this.color5, this.color6] 352 353 build() { 354 RelativeContainer() { 355 Row() { 356 Rect().height(25).width(this.item * 600 / this.max).foregroundColor(this.colorArray[this.index]).radius(5) 357 .align(Alignment.Start) 358 Text(" "+this.item) 359 .fontSize(17) 360 } 361 }.height(28) 362 } 363} 364``` 365 366
