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-universal-attributes-size.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**|
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>A value less than 0 evaluates to the default value.|
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. The maximum length is 9.|
218| maxValue | number | Yes| Maximum value displayed in the data panel.<br>Default value: **100**|
219
220## Example
221
222### Example 1
223
224```ts
225// xxx.ets
226@Entry
227@Component
228struct DataPanelExample {
229  public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10]
230
231  build() {
232    Column({ space: 5 }) {
233      Row() {
234        Stack() {
235          DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168)
236          Column() {
237            Text('30').fontSize(35).fontColor('#182431')
238            Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6)
239          }
240
241          Text('%')
242            .fontSize(9.33)
243            .lineHeight(12.83)
244            .fontWeight(500)
245            .opacity(0.6)
246            .position({ x: 104.42, y: 78.17 })
247        }.margin({ right: 44 })
248
249        Stack() {
250          DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168)
251          Column() {
252            Text('75').fontSize(35).fontColor('#182431')
253            Text('Used: 98 GB/128 GB').fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6)
254          }
255
256          Text('%')
257            .fontSize(9.33)
258            .lineHeight(12.83)
259            .fontWeight(500)
260            .opacity(0.6)
261            .position({ x: 104.42, y: 78.17 })
262        }
263      }.margin({ bottom: 59 })
264
265      DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20)
266    }.width('100%').margin({ top: 5 })
267  }
268}
269```
270
271![dataPanel](figures/dataPanel.PNG)
272
273### Example 2
274
275```ts
276// xxx.ets
277@Entry
278@Component
279struct LinearGradientDataPanelExample {
280  public values1: number[] = [20, 20, 20, 20]
281  public color1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }])
282  public color2: LinearGradient = new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }])
283  public colorShadow1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }])
284  public colorShadow2: LinearGradient = new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }])
285  public colorShadow3: LinearGradient = new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }])
286  public colorShadow4: LinearGradient = new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }])
287  @State color3: string = '#00FF00'
288  @State color4: string = '#20FF0000'
289  @State bgColor: string = '#08182431'
290  @State offsetX: number = 15
291  @State offsetY: number = 15
292  @State radius: number = 5
293  @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4]
294  @State shadowColorArray: Array<LinearGradient | ResourceColor> = [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4]
295
296  build() {
297    Column({ space: 5 }) {
298      Text('LinearGradient').fontSize(9).fontColor(0xCCCCCC).textAlign(TextAlign.Start).width('100%').margin({ top: 20, left: 20})
299      DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle })
300        .width(300)
301        .height(300)
302        .valueColors(this.colorArray)
303        .trackShadow({
304          radius: this.radius,
305          colors: this.shadowColorArray,
306          offsetX: this.offsetX,
307          offsetY: this.offsetY
308        })
309        .strokeWidth(30)
310        .trackBackgroundColor(this.bgColor)
311    }.width('100%').margin({ top: 5 })
312  }
313}
314```
315
316![LinearGradientDataPanel](figures/LinearGradientDataPanel.PNG)
317
318### Example 3
319
320```ts
321// xxx.ets
322@Builder
323function buildDataPanel(config: DataPanelConfiguration) {
324  Column() {
325    Column() {
326      ForEach(config.values, (item: number, index: number) => {
327        ChildItem({ item: item, index: index, max:config.maxValue})
328      }, (item: string) => item)
329    }.padding(10)
330    Column() {
331      Line().width("100%").backgroundColor("#ff373737").margin({bottom:5})
332    }.padding({left: 20, right: 20})
333    Row() {
334      Text('Length=' + config.values.length + '    ').margin({ left: 10 }).align(Alignment.Start)
335      Text('Max=' + config.maxValue).margin({ left: 10 }).align(Alignment.Start)
336    }
337  }
338}
339
340class DataPanelBuilder implements ContentModifier<DataPanelConfiguration> {
341  constructor() {
342  }
343  applyContent () : WrappedBuilder<[DataPanelConfiguration]> {
344    return wrapBuilder(buildDataPanel)
345  }
346}
347
348@Entry
349@Component
350struct Index {
351  build() {
352    Column() {
353      Text("Data panel").margin({ top: 12 });
354      Row() {
355        DataPanel({ values: [12.3, 21.1, 13.4, 35.2, 26.0, 32.0], max: 140, type: DataPanelType.Circle })
356          .width(400).height(260)
357          .constraintSize({maxWidth: "100%"})
358          .padding({ top: 10 })
359          .contentModifier(new DataPanelBuilder())
360      }.margin(15).backgroundColor("#fff5f5f5")
361    }
362  }
363}
364
365@Component
366struct ChildItem {
367  @Prop item: number;
368  @Prop index: number;
369  @Prop max: number;
370  public color1: string = "#65ff00dd"
371  public color2: string = "#6500ff99"
372  public color3: string = "#65ffe600"
373  public color4: string = "#6595ff00"
374  public color5: string = "#65000dff"
375  public color6: string = "#650099ff"
376  public colorArray: Array<string> = [this.color1, this.color2, this.color3, this.color4, this.color5, this.color6]
377
378  build() {
379    RelativeContainer() {
380      Row() {
381        Rect().height(25).width(this.item * 600 / this.max).foregroundColor(this.colorArray[this.index]).radius(5)
382          .align(Alignment.Start)
383        Text(" "+this.item)
384          .fontSize(17)
385      }
386    }.height(28)
387  }
388}
389```
390![LinearGradientDataPanel](figures/ContentModifierDataPanel.jpg)
391