1# DataPanel 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 23DataPanel(options: DataPanelOptions) 24 25**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.ArkUI.ArkUI.Full 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | -------- | -------- | -------- | 35| options | [DataPanelOptions](#datapaneloptions对象说明)| 是 | 数据面板组件参数。 | 36 37## DataPanelOptions对象说明 38 39数据面板选项。 40 41**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 42 43**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 44 45**系统能力：** SystemCapability.ArkUI.ArkUI.Full 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ----------------- | -------- | ----- | -------- | -------- | 49| values | number[] | 否 | 否 | 数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。 | 50| max | number | 否 | 是 | - max大于0时，表示数据的最大值。<br/>- max小于等于0时，max等于value数组各项的和，按比例显示。<br/>默认值：100 | 51| type<sup>8+</sup> | [DataPanelType](#datapaneltype8枚举说明) | 否 | 是 | 数据面板的类型（不支持动态修改）。<br/>默认值：DataPanelType.Circle | 52 53 54## DataPanelType<sup>8+</sup>枚举说明 55 56数据面板的类型。 57 58**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 59 60**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.ArkUI.ArkUI.Full 63 64| 名称 | 值 | 说明 | 65| -------| - | ------------ | 66| Line | - | 线型数据面板。 | 67| Circle | - | 环形数据面板。 | 68 69 70## 属性 71 72除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 73 74### closeEffect 75 76closeEffect(value: boolean) 77 78设置是否关闭数据占比图表旋转动效和投影效果。若未设置[trackShadow](#trackshadow10)属性，则由该属性控制投影效果的开关，开启投影的效果为投影的默认效果。若设置了trackShadow属性，则由trackShadow属性值控制投影效果的开关。 79 80**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 81 82**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 83 84**系统能力：** SystemCapability.ArkUI.ArkUI.Full 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| ------ | ------- | ---- | ------------------------------------------------------ | 90| value | boolean | 是 | 关闭数据占比图表旋转动效和投影效果。<br/>默认值：false，false表示开启数据占比图表旋转动效和投影效果，true表示关闭数据占比图表旋转动效和投影效果。 | 91 92### valueColors<sup>10+</sup> 93 94valueColors(value: Array<ResourceColor | LinearGradient>) 95 96设置各数据段颜色。 97 98**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 99 100**系统能力：** SystemCapability.ArkUI.ArkUI.Full 101 102**参数：** 103 104| 参数名 | 类型 | 必填 | 说明 | 105| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 106| value | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | 是 | 各数据段颜色，ResourceColor为纯色，LinearGradient为渐变色。 | 107 108### trackBackgroundColor<sup>10+</sup> 109 110trackBackgroundColor(value: ResourceColor) 111 112设置底板颜色。 113 114**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 115 116**系统能力：** SystemCapability.ArkUI.ArkUI.Full 117 118**参数：** 119 120| 参数名 | 类型 | 必填 | 说明 | 121| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 122| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 底板颜色。<br/>默认值：'#08182431'，格式为十六进制ARGB值，前两位代表透明度。 | 123 124### strokeWidth<sup>10+</sup> 125 126strokeWidth(value: Length) 127 128设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。 129 130**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.ArkUI.ArkUI.Full 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 138| value | [Length](ts-types.md#length) | 是 | 圆环粗细。<br/>默认值：24<br/>单位：vp<br/>设置字符串类型参数时，如果不指定单位，默认单位为px，例如'10'，等同于'10px'。<br/>**说明：**<br/>设置小于0的值时，按默认值显示。<br/>请合理设置圆环粗细，当value大于圆环半径时，圆环粗细会自动设置为圆环半径的12%。如果value过大，圆环可能会消失。 | 139 140### trackShadow<sup>10+</sup> 141 142trackShadow(value: DataPanelShadowOptions) 143 144设置投影样式。 145 146**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 147 148**系统能力：** SystemCapability.ArkUI.ArkUI.Full 149 150**参数：** 151 152| 参数名 | 类型 | 必填 | 说明 | 153| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 154| value | [DataPanelShadowOptions](#datapanelshadowoptions10对象说明) | 是 | 投影样式。<br/>**说明：** <br/>设置为null时，不开启投影。 | 155 156### contentModifier<sup>12+</sup> 157 158contentModifier(modifier: ContentModifier\<DataPanelConfiguration>) 159 160定制DataPanel内容区的方法。 161 162**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 170| modifier | [ContentModifier\<DataPanelConfiguration>](#datapanelconfiguration12对象说明) | 是 | 在DataPanel组件上，定制内容区的方法。<br/>modifier： 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 171 172 173## DataPanelShadowOptions<sup>10+</sup>对象说明 174 175DataPanelShadowOptions继承自[MultiShadowOptions](ts-information-display-common.md#multishadowoptions)，具有MultiShadowOptions的全部属性。 176 177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181| 名称 | 类型 | 只读 | 可选 | 说明 | 182| ------------- | ------- | ---- | -------- | -------- | 183| colors | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | 否 | 是 | 各数据段投影的颜色。 <br/>默认值：与valueColors值相同 <br/>**说明：** <br/>若设置的投影颜色的个数少于数据段个数时，则显示的投影颜色的个数和设置的投影颜色个数一致。<br/>若设置的投影颜色的个数多于数据段个数时，则显示的投影颜色的个数和数据段个数一致。| 184 185## LinearGradient<sup>10+</sup> 186 187### constructor 188 189constructor(colorStops: ColorStop[]) 190 191线性渐变颜色描述。 192 193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 194 195**系统能力：** SystemCapability.ArkUI.ArkUI.Full 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| ------------- | ------- | ---- | -------- | 201| colorStops | [ColorStop](#colorstop10)[] | 是 | 存储渐变颜色和渐变点。| 202 203 204## ColorStop<sup>10+</sup> 205 206颜色断点类型，用于描述渐进色颜色断点。 207 208**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 209 210**系统能力：** SystemCapability.ArkUI.ArkUI.Full 211 212| 名称 | 类型 | 只读 | 可选 | 说明 | 213| ------------- | ------- | ---- | -------- | -------- | 214| color | [ResourceColor](ts-types.md#resourcecolor) | 否 | 否 | 颜色值。| 215| offset | [Length](ts-types.md#length) | 否 | 否 | 渐变色断点（0~1之间的比例值，若数据值小于0则置为0，若数据值大于1则置为1）。<br>**说明：** <br/>若传入字符串类型且内容为数字，则转换为对应的数值。<br/>例如'10vp'转换为10，'10%'转换为0.1。 | 216 217## DataPanelConfiguration<sup>12+</sup>对象说明 218 219开发者需要自定义class实现ContentModifier接口。继承自[CommonConfiguration](ts-universal-attributes-content-modifier.md#commonconfigurationt)。 220 221**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 222 223**系统能力：** SystemCapability.ArkUI.ArkUI.Full 224 225| 名称 | 类型 | 只读 | 可选 | 说明 | 226| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 227| values | number[] | 否 | 否 | 当前DataPanel的数据值。<br>取值范围：[0, 9]，若数据值小于0，则置为0。 | 228| maxValue | number | 否 | 否 | DataPanel显示的最大值。<br/>默认值：100。<br>**说明：** <br/>如果小于或等于0，maxValue将被设为values数组中所有项的总和，并按比例显示。 | 229 230## 示例 231 232### 示例1（设置数据面板类型） 233 234该示例通过type属性，实现了设置数据面板的类型的功能。 235 236```ts 237// xxx.ets 238@Entry 239@Component 240struct DataPanelExample { 241 public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10] 242 243 build() { 244 Column({ space: 5 }) { 245 Row() { 246 Stack() { 247 // 单段环形数据面板 248 DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168) 249 Column() { 250 Text('30').fontSize(35).fontColor('#182431') 251 Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6) 252 } 253 254 Text('%') 255 .fontSize(9.33) 256 .lineHeight(12.83) 257 .fontWeight(500) 258 .opacity(0.6) 259 .position({ x: 104.42, y: 78.17 }) 260 }.margin({ right: 44 }) 261 262 // 多段环形数据面板 263 Stack() { 264 DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168) 265 Column() { 266 Text('75').fontSize(35).fontColor('#182431') 267 Text('已使用98GB/128GB').fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6) 268 } 269 270 Text('%') 271 .fontSize(9.33) 272 .lineHeight(12.83) 273 .fontWeight(500) 274 .opacity(0.6) 275 .position({ x: 104.42, y: 78.17 }) 276 } 277 }.margin({ bottom: 59 }) 278 279 // 线形数据面板 280 DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20) 281 }.width('100%').margin({ top: 5 }) 282 } 283} 284``` 285 286 287 288### 示例2（设置渐变色和阴影） 289 290该示例通过[valueColors](#valuecolors10)和[trackShadow](#trackshadow10)接口设置[LinearGradient](#lineargradient10)颜色，实现了设置渐变色效果和阴影效果。 291 292```ts 293// xxx.ets 294@Entry 295@Component 296struct LinearGradientDataPanelExample { 297 public values1: number[] = [20, 20, 20, 20] 298 public color1: LinearGradient = 299 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }]) 300 public color2: LinearGradient = 301 new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }]) 302 public colorShadow1: LinearGradient = 303 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }]) 304 public colorShadow2: LinearGradient = 305 new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }]) 306 public colorShadow3: LinearGradient = 307 new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }]) 308 public colorShadow4: LinearGradient = 309 new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }]) 310 @State color3: string = '#00FF00' 311 @State color4: string = '#20FF0000' 312 @State bgColor: string = '#08182431' 313 @State offsetX: number = 15 314 @State offsetY: number = 15 315 @State radius: number = 5 316 @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4] 317 @State shadowColorArray: Array<LinearGradient | ResourceColor> = 318 [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4] 319 320 build() { 321 Column({ space: 5 }) { 322 Text('LinearGradient') 323 .fontSize(9) 324 .fontColor(0xCCCCCC) 325 .textAlign(TextAlign.Start) 326 .width('100%') 327 .margin({ top: 20, left: 20 }) 328 DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle }) 329 .width(300) 330 .height(300) 331 .valueColors(this.colorArray) 332 .trackShadow({ 333 radius: this.radius, 334 colors: this.shadowColorArray, 335 offsetX: this.offsetX, 336 offsetY: this.offsetY 337 }) 338 .strokeWidth(30) 339 .trackBackgroundColor(this.bgColor) 340 }.width('100%').margin({ top: 5 }) 341 } 342} 343``` 344 345 346 347### 示例3（设置关闭动画和阴影） 348 349该示例通过[closeEffect](#closeeffect)接口，实现了关闭数据面板动画和阴影的功能。 350 351```ts 352// xxx.ets 353@Entry 354@Component 355struct LinearGradientDataPanelExample { 356 public values1: number[] = [20, 20, 20, 20] 357 public color1: LinearGradient = 358 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }]) 359 public color2: LinearGradient = 360 new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }]) 361 public colorShadow1: LinearGradient = 362 new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }]) 363 public colorShadow2: LinearGradient = 364 new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }]) 365 public colorShadow3: LinearGradient = 366 new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }]) 367 public colorShadow4: LinearGradient = 368 new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }]) 369 @State color3: string = '#00FF00' 370 @State color4: string = '#20FF0000' 371 @State bgColor: string = '#08182431' 372 @State offsetX: number = 15 373 @State offsetY: number = 15 374 @State radius: number = 5 375 @State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4] 376 @State shadowColorArray: Array<LinearGradient | ResourceColor> = 377 [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4] 378 379 build() { 380 Column({ space: 5 }) { 381 Text('LinearGradient') 382 .fontSize(9) 383 .fontColor(0xCCCCCC) 384 .textAlign(TextAlign.Start) 385 .width('100%') 386 .margin({ top: 20, left: 20 }) 387 DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle }) 388 .width(300) 389 .height(300) 390 .valueColors(this.colorArray) 391 .strokeWidth(30) 392 .closeEffect(true) 393 .trackBackgroundColor(this.bgColor) 394 }.width('100%').margin({ top: 5 }) 395 } 396} 397``` 398 399 400 401### 示例4（设置定制内容区） 402 403该示例通过[contentModifier](#contentmodifier12)接口，实现了定制数据面板内容区的功能。 404 405```ts 406// xxx.ets 407@Builder 408function buildDataPanel(config: DataPanelConfiguration) { 409 Column() { 410 Column() { 411 ForEach(config.values, (item: number, index: number) => { 412 ChildItem({ item: item, index: index, max: config.maxValue }) 413 }, (item: number, index: number) => item.toString()) 414 }.padding(10) 415 416 Column() { 417 Line().width("100%").backgroundColor("#ff373737").margin({ bottom: 5 }) 418 }.padding({ left: 20, right: 20 }) 419 420 Row() { 421 Text('Length=' + config.values.length + ' ').margin({ left: 10 }).align(Alignment.Start) 422 Text('Max=' + config.maxValue).margin({ left: 10 }).align(Alignment.Start) 423 } 424 } 425} 426 427class DataPanelBuilder implements ContentModifier<DataPanelConfiguration> { 428 constructor() { 429 } 430 431 applyContent(): WrappedBuilder<[DataPanelConfiguration]> { 432 return wrapBuilder(buildDataPanel) 433 } 434} 435 436@Entry 437@Component 438struct Index { 439 build() { 440 Column() { 441 Text("Data panel").margin({ top: 12 }); 442 Row() { 443 DataPanel({ values: [12.3, 21.1, 13.4, 35.2, 26.0, 32.0], max: 140, type: DataPanelType.Circle }) 444 .width(400) 445 .height(260) 446 .constraintSize({ maxWidth: "100%" }) 447 .padding({ top: 10 }) 448 .contentModifier(new DataPanelBuilder()) 449 }.margin(15).backgroundColor("#fff5f5f5") 450 } 451 } 452} 453 454@Component 455struct ChildItem { 456 @Prop item: number; 457 @Prop index: number; 458 @Prop max: number; 459 public color1: string = "#65ff00dd" 460 public color2: string = "#6500ff99" 461 public color3: string = "#65ffe600" 462 public color4: string = "#6595ff00" 463 public color5: string = "#65000dff" 464 public color6: string = "#650099ff" 465 public colorArray: Array<string> = [this.color1, this.color2, this.color3, this.color4, this.color5, this.color6] 466 467 build() { 468 RelativeContainer() { 469 Row() { 470 Rect() 471 .height(25) 472 .width(this.item * 600 / this.max) 473 .foregroundColor((this.index < 0 || this.index >= this.colorArray.length) ? this.colorArray[0] : 474 this.colorArray[this.index]) 475 .radius(5) 476 .align(Alignment.Start) 477 Text(" " + this.item) 478 .fontSize(17) 479 } 480 }.height(28) 481 } 482} 483``` 484 485
