1# DataPanel 2 3数据面板组件，用于将多个数据占比情况使用占比图进行展示。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17DataPanel(options: DataPanelOptions) 18 19**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| -------- | -------- | -------- | -------- | 29| options | [DataPanelOptions](#datapaneloptions对象说明)| 是 | 数据面板组件参数。 | 30 31## DataPanelOptions对象说明 32 33**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 34 35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39| 名称 | 类型 | 必填 | 说明 | 40| ----------------- | -------- | ----- | -------- | 41| values | number[] | 是 | 数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。 | 42| max | number | 否 | - max大于0，表示数据的最大值。<br/>- max小于等于0，max等于value数组各项的和，按比例显示。<br/>默认值：100 | 43| type<sup>8+</sup> | [DataPanelType](#datapaneltype8枚举说明) | 否 | 数据面板的类型（不支持动态修改）。<br/>默认值：DataPanelType.Circle | 44 45 46## DataPanelType<sup>8+</sup>枚举说明 47 48**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 49 50**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 51 52**系统能力：** SystemCapability.ArkUI.ArkUI.Full 53 54| 名称 | 说明 | 55| -------| ------------ | 56| Line | 线型数据面板。 | 57| Circle | 环形数据面板。 | 58 59 60## 属性 61 62除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 63 64### closeEffect 65 66closeEffect(value: boolean) 67 68设置关闭数据占比图表旋转动效和投影效果。若未设置[trackShadow属性](#trackshadow10)，则该属性控制投影效果的开关，开启投影的效果为投影的默认效果。若设置trackShadow属性，则由trackShadow属性值控制投影效果的开关。 69 70**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | ------- | ---- | ------------------------------------------------------ | 80| value | boolean | 是 | 关闭数据占比图表旋转动效和投影效果。<br/>默认值：false | 81 82### valueColors<sup>10+</sup> 83 84valueColors(value: Array<ResourceColor | LinearGradient>) 85 86设置各数据段颜色。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.ArkUI.ArkUI.Full 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | 96| value | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | 是 | 各数据段颜色，ResourceColor为纯色，LinearGradient为渐变色。 | 97 98### trackBackgroundColor<sup>10+</sup> 99 100trackBackgroundColor(value: ResourceColor) 101 102设置底板颜色。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 112| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 底板颜色。<br/>默认值：'#08182431'，格式为十六进制ARGB值，前俩位代表透明度。 | 113 114### strokeWidth<sup>10+</sup> 115 116strokeWidth(value: Length) 117 118设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。 119 120**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 121 122**系统能力：** SystemCapability.ArkUI.ArkUI.Full 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| ------ | ---------------------------- | ---- | ------------------------------------------------------------ | 128| value | [Length](ts-types.md#length) | 是 | 圆环粗细。<br/>默认值：24<br/>单位：vp<br/>**说明：** <br/>设置小于0的值时，按默认值显示。<br/>请合理设置圆环粗细，当value大于圆环半径时，圆环粗细会自动设置为圆环半径的12%。当value过大时，圆环可能会消失。 | 129 130### trackShadow<sup>10+</sup> 131 132trackShadow(value: DataPanelShadowOptions) 133 134设置投影样式。 135 136**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.ArkUI.ArkUI.Full 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ------ | ----------------------------------------------------------- | ---- | ----------------------------------------------------- | 144| value | [DataPanelShadowOptions](#datapanelshadowoptions10对象说明) | 是 | 投影样式。<br/>**说明：** <br/>设置null为不开启投影。 | 145 146### contentModifier<sup>12+</sup> 147 148contentModifier(modifier: ContentModifier\<DataPanelConfiguration>) 149 150定制DataPanel内容区的方法。 151 152**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 153 154**系统能力：** SystemCapability.ArkUI.ArkUI.Full 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 160| modifier | [ContentModifier\<DataPanelConfiguration>](#datapanelconfiguration12对象说明) | 是 | 在DataPanel组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 161 162 163## DataPanelShadowOptions<sup>10+</sup>对象说明 164 165DataPanelShadowOptions继承自[MultiShadowOptions](ts-types.md#multishadowoptions10)，具有MultiShadowOptions的全部属性。 166 167**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171| 名称 | 类型 | 必填 | 说明 | 172| ------------- | ------- | ---- | -------- | 173| colors | Array<[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient](#lineargradient10)> | 否 | 各数据段投影的颜色。 <br/>默认值：与valueColors值相同 <br/>**说明：** <br/>若设置的投影颜色的个数少于数据段个数时，则显示的投影颜色的个数和设置的投影颜色个数一致。<br/>若设置的投影颜色的个数多于数据段个数时，则显示的投影颜色的个数和数据段个数一致。| 174 175## LinearGradient<sup>10+</sup> 176 177### constructor 178 179constructor(colorStops: ColorStop[]) 180 181线性渐变颜色描述。 182 183**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 184 185**系统能力：** SystemCapability.ArkUI.ArkUI.Full 186 187**参数：** 188 189| 参数名 | 类型 | 必填 | 说明 | 190| ------------- | ------- | ---- | -------- | 191| colorStops | [ColorStop](#colorstop10)[] | 是 | 存储渐变颜色和渐变点。| 192 193 194## ColorStop<sup>10+</sup> 195 196颜色断点类型，用于描述渐进色颜色断点。 197 198**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.ArkUI.ArkUI.Full 201 202| 名称 | 类型 | 必填 | 说明 | 203| ------------- | ------- | ---- | -------- | 204| color | [ResourceColor](ts-types.md#resourcecolor) | 是 | 颜色值。| 205| offset | [Length](ts-types.md#length) | 是 | 渐变色断点（0~1之间的比例值，若数据值小于0则置为0，若数据值大于1则置为1）。<br>**说明：** <br/>若传入字符串类型且内容为数字，则转换为对应的数值。<br/>例如'10vp'转换为10，'10%'转换为0.1。 | 206 207## DataPanelConfiguration<sup>12+</sup>对象说明 208 209开发者需要自定义class实现ContentModifier接口。 210 211**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 212 213**系统能力：** SystemCapability.ArkUI.ArkUI.Full 214 215| 名称 | 类型 | 必填 | 说明 | 216| ------ | ------ | ------ |-------------------------------- | 217| values | number[] | 是 | 当前DataPanel的数据值，最大长度为9。 | 218| maxValue | number | 是 | DataPanel显示的最大值。<br/>默认值：100。 | 219 220## 示例 221 222### 示例1（设置数据面板类型） 223 224该示例通过type属性，实现了设置数据面板的类型的功能。 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 // 单段环形数据面板 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 // 多段环形数据面板 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('已使用98GB/128GB').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 // 线形数据面板 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### 示例2（设置渐变色和阴影） 279 280该示例通过valueColors和trackShadow接口设置LinearGradient颜色，实现了设置渐变色效果和阴影效果。 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### 示例3（设置关闭动画和阴影） 338 339该示例通过closeEffect接口，实现了关闭数据面板动画和阴影的功能。 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### 示例4（设置定制内容区） 392 393该示例通过contentModifier接口，实现了定制数据面板内容区的功能。 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
