1# Rating 2 3提供在给定范围内选择评分的组件。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12无 13 14 15## 接口 16 17Rating(options?: { rating: number, indicator?: boolean }) 18 19**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.ArkUI.ArkUI.Full 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| --------- | ------- | ---- | ------------------------------------------------------------ | 29| rating | number | 是 | 设置并接收评分值。<br/>默认值：0<br/>取值范围： [0, stars]<br/>小于0取0，大于stars取最大值stars。<br />从API version 10开始，该参数支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 | 30| indicator | boolean | 否 | 设置评分组件作为指示器使用，不可改变评分。<br/>默认值：false, 可进行评分<br/>**说明：** <br/>indicator=true时，默认组件高度height=12.0vp，组件width=height * stars。 <br/>indicator=false时，默认组件高度height=28.0vp，组件width=height * stars。 | 31 32## 属性 33 34### stars 35 36stars(value: number) 37 38设置评分总数。设置为小于等于0的值时，按默认值显示。 39 40**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 41 42**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 43 44**系统能力：** SystemCapability.ArkUI.ArkUI.Full 45 46**参数：** 47 48| 参数名 | 类型 | 必填 | 说明 | 49| ------ | ------ | ---- | ---------------------------- | 50| value | number | 是 | 设置评分总数。<br/>默认值：5 | 51 52### stepSize 53 54stepSize(value: number) 55 56设置操作评级的步长。设置为小于0.1的值时，按默认值显示。 57 58**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 59 60**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.ArkUI.ArkUI.Full 63 64**参数：** 65 66| 参数名 | 类型 | 必填 | 说明 | 67| ------ | ------ | ---- | ----------------------------------------------------------- | 68| value | number | 是 | 操作评级的步长。<br/>默认值：0.5<br/>取值范围：[0.1, stars] | 69 70### starStyle 71 72starStyle(value: { backgroundUri: string, foregroundUri: string, secondaryUri?: string }) 73 74设置评分的样式。该属性所支持的图片类型能力参考[Image](ts-basic-components-image.md)组件。 75 76支持加载本地图片和网络图片，暂不支持PixelMap类型和Resource资源。 77 78默认图片加载方式为异步，暂不支持同步加载。 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 | {<br/>backgroundUri: string,<br/>foregroundUri: string,<br/>secondaryUri?: string<br/>} | 是 | backgroundUri：未选中的星级的图片链接，可由用户自定义或使用系统默认图片。<br/>foregroundUri：选中的星级的图片路径，可由用户自定义或使用系统默认图片。<br/>secondaryUri：部分选中的星级的图片路径，可由用户自定义或使用系统默认图片。<br/>**说明：** <br/>backgroundUri或者foregroundUri或者secondaryUri设置的图片路径错误时，图片不显示。<br/>backgroundUri或者foregroundUri设置为undefined或者空字符串时，rating会选择加载系统默认星型图源。<br/>secondaryUri不设置或者设置的值为undefined或者空字符串时，优先设置为backgroundUri，效果上等同于只设置了foregroundUri、backgroundUri。 | 91 92> **说明：** 93> 94> rating宽高为[width, height]时，单个图片的绘制区域为[width / stars, height]。 95> 96> 为了指定绘制区域为方形，建议自定义宽高时采取[height * stars, height], width = height * stars的方式。 97 98### contentModifier<sup>12+</sup> 99 100contentModifier(modifier: ContentModifier\<RatingConfiguration>) 101 102定制Rating内容区的方法。 103 104**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.ArkUI.ArkUI.Full 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 112| modifier | [ContentModifier\<RatingConfiguration>](#ratingconfiguration12对象说明) | 是 | 在Rating组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 113 114 115## 事件 116 117### onChange 118 119onChange(callback:(value: number) => void) 120 121操作评分条的评星发生改变时触发该回调。 122 123**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 124 125**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 126 127**系统能力：** SystemCapability.ArkUI.ArkUI.Full 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------ | ------ | ---- | -------------- | 133| value | number | 是 | 评分条的评分。 | 134 135## 键盘走焦规格 136| 按键 | 功能描述 | 137|------------|-----------------------------| 138| Tab | 组件间切换焦点。 | 139| 左右方向键 | 评分预览增加/减少（步长为step），不改变实际分值。 | 140| Home | 移动到第一个星星， 不改变实际分值。 | 141| End | 移动到最后一个星星， 不改变实际分值。 | 142| Space/Enter | 根据当前评分提交评分结果。 | 143 144## RatingConfiguration<sup>12+</sup>对象说明 145 146开发者需要自定义class实现ContentModifier接口。 147 148**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152| 名称 | 类型 | 只读 | 可选 | 说明 | 153| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 154| rating | number | 否 | 否 |评分条当前评分数。<br/>默认值：0 | 155| indicator | boolean | 否 | 否 | 评分条是否作为一个指示器。<br/>默认值：false | 156| stars | number | 否 | 否 |评分条的星级总数。<br/>默认值：5 | 157| stepSize | number | 否 | 否 |评分条的评分步长。<br/>默认值：0.5 | 158| triggerChange | Callback\<number> | 否 | 否 |触发评分数量变化。 | 159 160## 示例 161 162### 示例1（设置默认评分样式） 163 164该示例为创建默认星型评分样式。 165 166```ts 167// xxx.ets 168@Entry 169@Component 170struct RatingExample { 171 @State rating: number = 3.5 172 173 build() { 174 Column() { 175 Column() { 176 Rating({ rating: this.rating, indicator: false }) 177 .stars(5) 178 .stepSize(0.5) 179 .margin({ top: 24 }) 180 .onChange((value: number) => { 181 this.rating = value 182 }) 183 Text('current score is ' + this.rating) 184 .fontSize(16) 185 .fontColor('rgba(24,36,49,0.60)') 186 .margin({ top: 16 }) 187 }.width(360).height(113).backgroundColor('#FFFFFF').margin({ top: 68 }) 188 189 Row() { 190 Image('common/testImage.jpg') 191 .width(40) 192 .height(40) 193 .borderRadius(20) 194 .margin({ left: 24 }) 195 Column() { 196 Text('Yue') 197 .fontSize(16) 198 .fontColor('#182431') 199 .fontWeight(500) 200 Row() { 201 Rating({ rating: 3.5, indicator: false }).margin({ top: 1, right: 8 }) 202 Text('2021/06/02') 203 .fontSize(10) 204 .fontColor('#182431') 205 } 206 }.margin({ left: 12 }).alignItems(HorizontalAlign.Start) 207 208 Text('1st Floor') 209 .fontSize(10) 210 .fontColor('#182431') 211 .position({ x: 295, y: 8 }) 212 }.width(360).height(56).backgroundColor('#FFFFFF').margin({ top: 64 }) 213 }.width('100%').height('100%').backgroundColor('#F1F3F5') 214 } 215} 216``` 217 218 219 220### 示例2（设置评分的样式） 221 222该示例通过配置starStyle实现自定义星级的图片链接。 223 224```ts 225// xxx.ets 226@Entry 227@Component 228struct RatingExample { 229 @State rating: number = 3.5 230 231 build() { 232 Column() { 233 Rating({ rating: this.rating, indicator: false }) 234 .stars(5) 235 .stepSize(0.5) 236 .starStyle({ 237 backgroundUri: '/common/imag1.png', // common目录与pages同级 238 foregroundUri: '/common/imag2.png', 239 secondaryUri: '/common/imag3.png' 240 }) 241 .margin({ top: 24 }) 242 .onChange((value: number) => { 243 this.rating = value 244 }) 245 Text('current score is ' + this.rating) 246 .fontSize(16) 247 .fontColor('rgba(24,36,49,0.60)') 248 .margin({ top: 16 }) 249 }.width('100%').height('100%').backgroundColor('#F1F3F5') 250 } 251} 252``` 253 254 255 256### 示例3（自定义评分条） 257该示例实现了自定义评分条的功能，每个圆圈表示0.5分。ratingIndicator为true时表示评分条作为一个指示器不可改变评分； 258为false时可以进行评分。ratingStars可改变评分总数。ratingStepsize可改变评分步长。 259 260```ts 261// xxx.ets 262class MyRatingStyle implements ContentModifier<RatingConfiguration> { 263 name: string = "" 264 style: number = 0 265 constructor(value1: string, value2: number) { 266 this.name = value1 267 this.style = value2 268 } 269 applyContent() : WrappedBuilder<[RatingConfiguration]> { 270 return wrapBuilder(buildRating) 271 } 272} 273 274@Builder function buildRating(config: RatingConfiguration) { 275 Column() { 276 Row() { 277 Circle({ width: 25, height: 25 }) 278 .fill(config.rating >= 0.4 ? Color.Black : Color.Red) 279 .onClick((event: ClickEvent) => { 280 if (!config.indicator) { 281 if (config.stepSize = 0.5) { 282 config.triggerChange(0.5); 283 return 284 } 285 if (config.stepSize = 1) { 286 config.triggerChange(1); 287 return 288 } 289 } 290 }).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden) 291 Circle({ width: 25, height: 25 }) 292 .fill(config.rating >= 0.9 ? Color.Black : Color.Red) 293 .onClick((event: ClickEvent) => { 294 if (!config.indicator) { 295 config.triggerChange(1); 296 } 297 }).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden) 298 Circle({ width: 25, height: 25 }) 299 .fill(config.rating >= 1.4 ? Color.Black : Color.Red) 300 .onClick((event: ClickEvent) => { 301 if (!config.indicator) { 302 if (config.stepSize = 0.5) { 303 config.triggerChange(1.5); 304 return 305 } 306 if (config.stepSize = 1) { 307 config.triggerChange(2); 308 return 309 } 310 } 311 }).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden).margin({left:10}) 312 Circle({ width: 25, height: 25 }) 313 .fill(config.rating >= 1.9 ? Color.Black : Color.Red) 314 .onClick((event: ClickEvent) => { 315 if (!config.indicator) { 316 config.triggerChange(2); 317 } 318 }).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden) 319 Circle({ width: 25, height: 25 }) 320 .fill(config.rating >= 2.4 ? Color.Black : Color.Red) 321 .onClick((event: ClickEvent) => { 322 if (!config.indicator) { 323 if (config.stepSize = 0.5) { 324 config.triggerChange(2.5); 325 return 326 } 327 if (config.stepSize = 1) { 328 config.triggerChange(3); 329 return 330 } 331 } 332 }).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden).margin({left:10}) 333 Circle({ width: 25, height: 25 }) 334 .fill(config.rating >= 2.9 ? Color.Black : Color.Red) 335 .onClick((event: ClickEvent) => { 336 if (!config.indicator) { 337 config.triggerChange(3); 338 } 339 }).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden) 340 Circle({ width: 25, height: 25 }) 341 .fill(config.rating >= 3.4 ? Color.Black : Color.Red) 342 .onClick((event: ClickEvent) => { 343 if (!config.indicator) { 344 if (config.stepSize = 0.5) { 345 config.triggerChange(3.5); 346 return 347 } 348 if (config.stepSize = 1) { 349 config.triggerChange(4); 350 return 351 } 352 } 353 }).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden).margin({left:10}) 354 Circle({ width: 25, height: 25 }) 355 .fill(config.rating >= 3.9 ? Color.Black : Color.Red) 356 .onClick((event: ClickEvent) => { 357 if (!config.indicator) { 358 config.triggerChange(4); 359 } 360 }).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden) 361 Circle({ width: 25, height: 25 }) 362 .fill(config.rating >= 4.4 ? Color.Black : Color.Red) 363 .onClick((event: ClickEvent) => { 364 if (!config.indicator) { 365 if (config.stepSize = 0.5) { 366 config.triggerChange(4.5); 367 return 368 } 369 if (config.stepSize = 1) { 370 config.triggerChange(5); 371 return 372 } 373 } 374 }).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden).margin({left:10}) 375 Circle({ width: 25, height: 25 }) 376 .fill(config.rating >= 4.9 ? Color.Black : Color.Red) 377 .onClick((event: ClickEvent) => { 378 if (!config.indicator) { 379 config.triggerChange(5); 380 } 381 }).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden) 382 } 383 Text("分值：" + config.rating) 384 } 385} 386 387@Entry 388@Component 389struct ratingExample { 390 @State rating: number = 0; 391 @State ratingIndicator: boolean = true; 392 @State ratingStars: number = 0; 393 @State ratingStepsize: number = 0.5; 394 @State ratingEnabled: boolean = true; 395 build() { 396 Row() { 397 Column() { 398 Rating({ 399 rating: 0, 400 indicator: this.ratingIndicator 401 }) 402 .stepSize(this.ratingStepsize) 403 .stars(this.ratingStars) 404 .backgroundColor(Color.Transparent) 405 .width('100%') 406 .height(50) 407 .onChange((value: number) => { 408 console.info('Rating change is'+ value); 409 this.rating = value 410 }) 411 .contentModifier(new MyRatingStyle("hello", 3)) 412 Button(this.ratingIndicator ? "ratingIndicator : true" : "ratingIndicator : false") 413 .onClick((event) => { 414 if (this.ratingIndicator) { 415 this.ratingIndicator = false 416 } else { 417 this.ratingIndicator = true 418 } 419 }).margin({top : 5}) 420 421 Button(this.ratingStars < 5 ? "ratingStars + 1, ratingStars =" + this.ratingStars : "ratingStars最大值为5") 422 .onClick((event) => { 423 if (this.ratingStars < 5) { 424 this.ratingStars += 1 425 } 426 }).margin({top : 5}) 427 428 Button(this.ratingStars > 0 ? "ratingStars - 1, ratingStars =" + this.ratingStars : "ratingStars小于等于0时默认等于5") 429 .onClick((event) => { 430 if (this.ratingStars > 0) { 431 this.ratingStars -= 1 432 } 433 }).margin({top : 5}) 434 435 Button(this.ratingStepsize == 0.5 ? "ratingStepsize : 0.5" : "ratingStepsize : 1") 436 .onClick((event) => { 437 if (this.ratingStepsize == 0.5) { 438 this.ratingStepsize = 1 439 } else { 440 this.ratingStepsize = 0.5 441 } 442 }).margin({top : 5}) 443 } 444 .width('100%') 445 .height('100%') 446 .justifyContent(FlexAlign.Center) 447 } 448 .height('100%') 449 } 450} 451``` 452 453
