1# Gauge 2 3数据量规图表组件，用于将数据展示为环形图表。 4 5 6> **说明：** 7> 8> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 9 10 11## 子组件 12 13可以包含单个子组件。 14 15> **说明：** 16> 17> 建议使用文本组件构建当前数值文本和辅助文本。 18> 19> 若子组件宽高为百分比形式，则基准范围为以外圆环做为内切圆的矩形。 20 21 22## 接口 23 24Gauge(options:{value: number, min?: number, max?: number}) 25 26从API version 9开始，该接口支持在ArkTS卡片中使用。 27 28**参数：** 29 30| 参数名 | 参数类型 | 必填 | 参数描述 | 31| -------- | -------- | -------- | -------- | 32| value | number | 是 | 量规图的当前数据值，即图中指针指向位置。用于组件创建时量规图初始值的预置。<br/>**说明：** <br/>value不在min和max范围内时使用min作为默认值。 | 33| min | number | 否 | 当前数据段最小值。<br/>默认值：0 | 34| max | number | 否 | 当前数据段最大值。<br/>默认值：100<br/>**说明：** <br/>max小于min时使用默认值0和100。<br/>max和min支持负数。 | 35 36## 属性 37 38除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 39 40| 名称 | 参数类型 | 描述 | 41| -------- | -------- | -------- | 42| value | number | 设置量规图的数据值，可用于动态修改量规图的数据值。<br/>默认值：0<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 43| startAngle | number | 设置起始角度位置，时钟0点为0度，顺时针方向为正角度。<br/>默认值：0<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 44| endAngle | number | 设置终止角度位置，时钟0点为0度，顺时针方向为正角度。<br/>默认值：360<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 | 45| colors | [ResourceColor<sup>11+</sup>](ts-types.md#resourcecolor) \| [LinearGradient<sup>11+</sup>](ts-basic-components-datapanel.md#lineargradient10对象说明) \| Array<[[ResourceColor](ts-types.md#resourcecolor) \| [LinearGradient<sup>11+</sup>](ts-basic-components-datapanel.md#lineargradient10对象说明) \| number]> | 设置量规图的颜色，支持分段颜色设置。<br/>API version 9 默认值：Color.Black<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。 <br/>从API version 11开始，该接口使用以下规则：<br/> 参数类型为ResourceColor，则圆环类型为单色环。<br/> 参数类型为LinearGradient，则圆环类型为渐变环。<br/> 参数类型为数组，则圆环类型为分段渐变环。<br/> 分段渐变环最大显示段数为9段，若多于9段，则多于部分不显示。第一个参数为颜色值，若设置为非颜色类型，则置为"0xFFE84026"。第二个参数为颜色所占比重，若设置为负数或是非数值类型，则将比重置为0。<br/>API version 11默认值：<br>若不传颜色，或者数组为空，无法确定圆环类型及颜色，则圆环颜色为"0xFF64BB5C"、"0xFFF7CE00"、"0xFFE84026"的渐变环。<br/>若传入颜色，但颜色值有误，则该颜色为"0xFFE84026"。 | 46| strokeWidth | [Length](ts-types.md#length) | 设置环形量规图的环形厚度。<br/>默认值：4<br/>单位：vp<br/>从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**说明：** <br/>设置小于0的值时，按默认值显示。<br/>不支持百分比。 | 47| description<sup>11+</sup> | [CustomBuilder](ts-types.md#custombuilder8) | 设置说明文本。<br/>**说明：** <br/>@Builder中的内容由开发者自定义，建议使用文本或者图片。<br/>若自定义部分的宽高为百分比形式，则基准范围为圆环直径的44.4%*25.4%的矩形（图片为28.6%*28.6%），距离圆环底部0vp，左右居中。<br/>设置null则不显示内容。<br/>不设置则依赖是否设置数据最大最小值。<br/>若设置最大最小值或者只设置其中一个，则显示最大最小值。<br/>若未设置最大最小值，则不显示内容。<br/>最大最小值显示在圆环底部，位置不可移动，若圆环开口角度设置不恰当，存在圆环遮挡文字的情况。 | 48| trackShadow<sup>11+</sup> | [GaugeShadowOptions](#gaugeshadowoptions11对象说明) | 设置阴影样式。<br/>**说明：** <br/>阴影颜色与圆环颜色一致。<br/>设置null为不开启投影。| 49| indicator<sup>11+</sup> | [GaugeIndicatorOptions](#gaugeindicatoroptions11对象说明) | 设置指针样式。<br/>**说明：** <br/>设置null则不显示指针。| 50 51## GaugeShadowOptions<sup>11+</sup>对象说明 52| 名称 | 参数类型 | 必填 | 描述 | 53| ------------- | ------- | ---- | -------- | 54| radius | number \| [Resource](ts-types.md#resource类型) | 否 | 投影模糊半径。 <br/>默认值：20<br/>单位：vp <br/>**说明：** <br/>设置小于等于0的值时，按默认值显示。| 55| offsetX | number \| [Resource](ts-types.md#resource类型) | 否 | X轴的偏移量。 <br/>默认值：5<br/>单位：vp | 56| offsetY | number \| [Resource](ts-types.md#resource类型) | 否 | Y轴的偏移量。 <br/>默认值：5<br/>单位：vp | 57 58## GaugeIndicatorOptions<sup>11+</sup>对象说明 59| 名称 | 参数类型 | 必填 | 描述 | 60| ------------- | ------- | ---- | -------- | 61| icon | [Resource](ts-types.md#resource类型) | 否 | 图标资源路径。<br/>**说明：** <br/>不配置则使用默认的三角形样式指针。<br/>支持使用svg格式的图标，若使用其他格式，则使用默认的三角形样式指针。 | 62| space | [Dimension](ts-types.md#dimension10) | 否 | 指针距离圆环外边的间距。(不支持百分比) <br/>默认值：8<br/>单位：vp <br/>**说明：** <br/> 对于默认的三角形样式指针，间距为黑色三角形到圆环外边的间距。<br/> 若设置值小于0，则使用默认值。<br/>若设置值大于圆环半径，则使用默认值。| 63 64## 示例 65### 示例1 66示例使用当前数值、说明文本、辅助文本。 67```ts 68@Entry 69@Component 70struct Gauge1 { 71 @Builder descriptionBuilder() { 72 Text('说明文本') 73 .maxFontSize('30sp') 74 .minFontSize("10.0vp") 75 .fontColor("#fffa2a2d") 76 .fontWeight(FontWeight.Medium) 77 .width('100%') 78 .height("100%") 79 .textAlign(TextAlign.Center) 80 } 81 82 build() { 83 Column() { 84 Gauge({ value: 50, min: 1, max: 100 }) { 85 Column() { 86 Text('50') 87 .fontWeight(FontWeight.Medium) 88 .width('62%') 89 .fontColor("#ff182431") 90 .maxFontSize("60.0vp") 91 .minFontSize("30.0vp") 92 .textAlign(TextAlign.Center) 93 .margin({ top: '35%' }) 94 .textOverflow({ overflow: TextOverflow.Ellipsis }) 95 .maxLines(1) 96 Text('辅助文本') 97 .maxFontSize("16.0fp") 98 .minFontSize("10.0vp") 99 .fontColor($r('sys.color.ohos_id_color_text_secondary')) 100 .fontColor($r('sys.color.ohos_id_color_text_secondary')) 101 .fontWeight(FontWeight.Regular) 102 .width('67.4%') 103 .height('9.5%') 104 .textAlign(TextAlign.Center) 105 }.width('100%').height('100%') 106 } 107 .value(50) 108 .startAngle(210) 109 .endAngle(150) 110 .colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9], 111 [new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8], 112 [new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7], 113 [new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6], 114 [new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5], 115 [new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4], 116 [new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3], 117 [new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2], 118 [new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]]) 119 .width('80%') 120 .height('80%') 121 .strokeWidth(18) 122 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 123 .description(this.descriptionBuilder) 124 .padding(18) 125 }.margin({ top: 40 }).width('100%').height('100%') 126 } 127} 128``` 129 130 131### 示例2 132示例使用当前数值、图标。 133```ts 134@Entry 135@Component 136struct Gauge2 { 137 @Builder descriptionBuilderImage() { 138 Image($r('sys.media.ohos_ic_public_clock')).width(72).height(72) 139 } 140 141 build() { 142 Column() { 143 Gauge({ value: 50, min: 1, max: 100 }) { 144 Column() { 145 Text('50') 146 .fontWeight(FontWeight.Medium) 147 .width('62%') 148 .fontColor("#ff182431") 149 .maxFontSize("60.0vp") 150 .minFontSize("30.0vp") 151 .textAlign(TextAlign.Center) 152 .margin({ top: '35%' }) 153 .textOverflow({ overflow: TextOverflow.Ellipsis }) 154 .maxLines(1) 155 }.width('100%').height('100%') 156 } 157 .startAngle(210) 158 .endAngle(150) 159 .colors('#cca5d61d') 160 .width('80%') 161 .height('80%') 162 .strokeWidth(18) 163 .description(this.descriptionBuilderImage) 164 .padding(18) 165 }.margin({ top: 40 }).width('100%').height('100%') 166 } 167} 168``` 169 170 171### 示例3 172示例使用当前数值、说明文本。 173```ts 174@Entry 175@Component 176struct Gauge3 { 177 @Builder descriptionBuilder() { 178 Text('说明文本') 179 .maxFontSize('30sp') 180 .minFontSize("10.0vp") 181 .fontColor("#fffa2a2d") 182 .fontWeight(FontWeight.Medium) 183 .width('100%') 184 .height("100%") 185 .textAlign(TextAlign.Center) 186 } 187 188 build() { 189 Column() { 190 Column() { 191 Gauge({ value: 50, min: 1, max: 100 }) { 192 Column() { 193 Text('50') 194 .fontWeight(FontWeight.Medium) 195 .width('62%') 196 .fontColor("#ff182431") 197 .maxFontSize("60.0vp") 198 .minFontSize("30.0vp") 199 .textAlign(TextAlign.Center) 200 .margin({ top: '35%' }) 201 .textOverflow({ overflow: TextOverflow.Ellipsis }) 202 .maxLines(1) 203 }.width('100%').height('100%') 204 } 205 .startAngle(210) 206 .endAngle(150) 207 .colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9], 208 [new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8], 209 [new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7], 210 [new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6], 211 [new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5], 212 [new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4], 213 [new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3], 214 [new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2], 215 [new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]]) 216 .width('80%') 217 .height('80%') 218 .strokeWidth(18) 219 .description(this.descriptionBuilder) 220 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 221 .padding(18) 222 }.margin({ top: 40 }).width('100%').height('100%') 223 } 224 } 225} 226``` 227 228 229### 示例4 230示例使用当前数值、辅助文本。 231```ts 232@Entry 233@Component 234struct Gauge4 { 235 build() { 236 Column() { 237 Gauge({ value: 50, min: 1, max: 100 }) { 238 Column() { 239 Text('50') 240 .maxFontSize("72.0vp") 241 .minFontSize("10.0vp") 242 .fontColor("#ff182431") 243 .width('40%') 244 .textAlign(TextAlign.Center) 245 .margin({ top: '35%' }) 246 .textOverflow({ overflow: TextOverflow.Ellipsis }) 247 .maxLines(1) 248 Text('辅助文本') 249 .maxFontSize("30.0vp") 250 .minFontSize("18.0vp") 251 .fontWeight(FontWeight.Medium) 252 .fontColor($r('sys.color.ohos_id_color_text_secondary')) 253 .width('62%') 254 .height('15.9%') 255 .textAlign(TextAlign.Center) 256 }.width('100%').height('100%') 257 } 258 .startAngle(210) 259 .endAngle(150) 260 .colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9], 261 [new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8], 262 [new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7], 263 [new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6], 264 [new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5], 265 [new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4], 266 [new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3], 267 [new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2], 268 [new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]]) 269 .width('80%') 270 .height('80%') 271 .strokeWidth(18) 272 .description(null) 273 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 274 .padding(18) 275 }.margin({ top: 40 }).width('100%').height('100%') 276 } 277} 278``` 279 280 281### 示例5 282示例使用当前数值、最大最小数值。 283```ts 284@Entry 285@Component 286struct Gauge5 { 287 build() { 288 Column() { 289 Gauge({ value: 50, min: 1, max: 100 }) { 290 Column() { 291 Text('50') 292 .maxFontSize("80sp") 293 .minFontSize("60.0vp") 294 .fontWeight(FontWeight.Medium) 295 .fontColor("#ff182431") 296 .width('40%') 297 .height('30%') 298 .textAlign(TextAlign.Center) 299 .margin({ top: '22.2%' }) 300 .textOverflow({ overflow: TextOverflow.Ellipsis }) 301 .maxLines(1) 302 }.width('100%').height('100%') 303 } 304 .startAngle(225) 305 .endAngle(135) 306 .colors(new LinearGradient([{ color: "#e84026", offset: 0 }, 307 { color: "#f7ce00", offset: 0.6 }, 308 { color: "#64bb5c", offset: 1 }])) 309 .width('80%') 310 .height('80%') 311 .strokeWidth(18) 312 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 313 .padding(18) 314 }.margin({ top: 40 }).width('100%').height('100%') 315 } 316} 317``` 318 319 320### 示例6 321示例使用当前数值、最大最小数值、辅助文本。 322```ts 323@Entry 324@Component 325struct Gauge6 { 326 build() { 327 Column() { 328 Gauge({ value: 50, min: 1, max: 100 }) { 329 Column() { 330 Text('50') 331 .maxFontSize('60sp') 332 .minFontSize('30.0vp') 333 .fontWeight(FontWeight.Medium) 334 .fontColor("#ff182431") 335 .width('62%') 336 .textAlign(TextAlign.Center) 337 .margin({ top: '35%' }) 338 .textOverflow({ overflow: TextOverflow.Ellipsis }) 339 .maxLines(1) 340 Text('辅助文本') 341 .maxFontSize('16sp') 342 .minFontSize("10.0vp") 343 .fontColor($r('sys.color.ohos_id_color_text_secondary')) 344 .fontWeight(FontWeight.Regular) 345 .width('67.4%') 346 .height('9.5%') 347 .textAlign(TextAlign.Center) 348 }.width('100%').height('100%') 349 } 350 .startAngle(225) 351 .endAngle(135) 352 .colors(Color.Red) 353 .width('80%') 354 .height('80%') 355 .indicator(null) 356 .strokeWidth(18) 357 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 358 .padding(18) 359 }.margin({ top: 40 }).width('100%').height('100%') 360 } 361} 362``` 363 364 365### 示例7 366示例使用当前数值、最大最小数值。 367```ts 368@Entry 369@Component 370struct Gauge7 { 371 build() { 372 Column() { 373 Gauge({ value: 50, min: 1, max: 100 }) { 374 Column() { 375 Text('50') 376 .maxFontSize('60sp') 377 .minFontSize('30.0vp') 378 .fontWeight(FontWeight.Medium) 379 .fontColor("#ff182431") 380 .width('62%') 381 .textAlign(TextAlign.Center) 382 .margin({ top: '35%' }) 383 .textOverflow({ overflow: TextOverflow.Ellipsis }) 384 .maxLines(1) 385 }.width('100%').height('100%') 386 } 387 .startAngle(225) 388 .endAngle(135) 389 .colors(Color.Red) 390 .width('80%') 391 .height('80%') 392 .indicator(null) 393 .strokeWidth(18) 394 .trackShadow({ radius: 7, offsetX: 7, offsetY: 7 }) 395 .padding(18) 396 }.margin({ top: 40 }).width('100%').height('100%') 397 } 398} 399``` 400
