鸿蒙 评分组件Rating

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

Rating组件是鸿蒙(HarmonyOS)中用于展示和收集评分的UI组件，支持星级评分、自定义图标、半星评分等功能。

一、基础用法

1. 基本评分展示

// 基础评分组件
@Entry
@Component
struct RatingExample {
  @State rating: number = 3.5 // 默认3.5星

  build() {
    Column() {
      // 基本使用
      Rating({
        rating: this.rating,
        indicator: false // 非指示器模式（可交互）
      })
      .stars(5) // 总星数
      .stepSize(0.5) // 步长0.5（支持半星）
      .onChange((value: number) => {
        this.rating = value // 评分变化时更新
        console.log('当前评分:', value)
      })
      
      Text(`当前评分: ${this.rating}`).margin(10)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

二、核心API

1. 评分控制属性

API	类型	默认值	描述	示例
rating	number	0	当前评分值	.rating(3.5)
stars	number	5	总星数	.stars(10)
stepSize	number	0.5	评分变化步长	.stepSize(1)
indicator	boolean	false	是否为指示器模式（不可交互）	.indicator(true)

2. 样式定制API

API	类型	默认值	描述	示例
starStyle	{ background: string, foreground: string, secondary?: string }	-	星形样式	.starStyle({ background: '#CCCCCC', foreground: '#FFD700' })
width	Length	父容器宽度	组件宽度	.width(200)
height	Length	父容器高度	组件高度	.height(40)

3. 交互事件API

API	参数	描述	示例
onChange	(value: number) => void	评分变化回调	.onChange((value) => {})
onAppear	() => void	组件出现回调	.onAppear(() => {})
onDisAppear	() => void	组件消失回调	.onDisAppear(() => {})

三、功能示例

1. 自定义星形样式

@Entry
@Component
struct CustomRatingExample {
  @State rating: number = 2.5

  build() {
    Column() {
      Rating()
        .rating(this.rating)
        .stars(5)
        .stepSize(0.5)
        .starStyle({
          background: '#DDDDDD', // 未选中的星颜色
          foreground: '#FF6347', // 选中的星颜色
          secondary: '#FFA07A' // 部分选中的星颜色(半星)
        })
        .width(300)
        .height(50)
        .onChange((value: number) => {
          this.rating = value
        })
      
      Text(`自定义样式评分: ${this.rating}`).margin(10)
    }
    .padding(20)
  }
}

2. 不同尺寸的Rating

@Entry
@Component
struct SizeRatingExample {
  @State smallRating: number = 3
  @State mediumRating: number = 4
  @State largeRating: number = 2.5

  build() {
    Column() {
      // 小尺寸
      Rating({ rating: this.smallRating })
        .width(150)
        .height(20)
        .onChange((value) => { this.smallRating = value })
      
      Text(`小尺寸: ${this.smallRating}`).margin(10)

      // 中尺寸
      Rating({ rating: this.mediumRating })
        .width(200)
        .height(30)
        .onChange((value) => { this.mediumRating = value })
      
      Text(`中尺寸: ${this.mediumRating}`).margin(10)

      // 大尺寸
      Rating({ rating: this.largeRating })
        .width(250)
        .height(40)
        .onChange((value) => { this.largeRating = value })
      
      Text(`大尺寸: ${this.largeRating}`).margin(10)
    }
  }
}

3. 只读评分指示器

@Entry
@Component
struct IndicatorRatingExample {
  @State currentScore: number = 4.2

  build() {
    Column() {
      // 只读评分展示
      Rating({ 
        rating: this.currentScore,
        indicator: true // 设置为指示器模式
      })
      .starStyle({
        background: '#EEEEEE',
        foreground: '#FFA500'
      })
      
      Slider({
        value: this.currentScore,
        min: 0,
        max: 5,
        step: 0.1
      })
      .onChange((value) => {
        this.currentScore = value
      })
      .width('80%')
      
      Text(`动态评分值: ${this.currentScore.toFixed(1)}`)
        .fontSize(16)
        .margin(10)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

四、高级功能实现

1. 自定义图标Rating

@Entry
@Component
struct CustomIconRating {
  @State rating: number = 3.5

  build() {
    Column() {
      // 使用自定义图标
      Rating({ rating: this.rating })
        .stars(5)
        .stepSize(0.5)
        .starStyle({
          background: $r('app.media.ic_star_outline'), // 未选中图标
          foreground: $r('app.media.ic_star_filled'), // 选中图标
          secondary: $r('app.media.ic_star_half') // 半星图标
        })
        .width(250)
        .height(40)
        .onChange((value) => {
          this.rating = value
        })
      
      Text(`自定义图标评分: ${this.rating}`)
        .fontSize(16)
        .margin(10)
    }
  }
}

2. 动态星星数量

@Entry
@Component
struct DynamicStarRating {
  @State starCount: number = 5
  @State currentRating: number = 0

  build() {
    Column() {
      // 动态星星数量
      Rating({ rating: this.currentRating })
        .stars(this.starCount)
        .width(200)
        .height(30)
        .onChange((value) => {
          this.currentRating = value
        })
      
      Row() {
        Button('3星')
          .onClick(() => { this.starCount = 3 })
        
        Button('5星')
          .onClick(() => { this.starCount = 5 })
          .margin(10)
        
        Button('10星')
          .onClick(() => { this.starCount = 10 })
      }
      .margin(20)
      
      Text(`当前: ${this.starCount}星制, 评分: ${this.currentRating}`)
        .fontSize(16)
    }
  }
}

3. 评分与动画结合

@Entry
@Component
struct AnimatedRating {
  @State rating: number = 0
  @State scale: number = 1

  build() {
    Column() {
      // 带动画效果的Rating
      Rating({ rating: this.rating })
        .stars(5)
        .width(200)
        .height(40)
        .scale({ x: this.scale, y: this.scale })
        .onChange((value) => {
          // 评分变化时触发动画
          this.rating = value
          this.scale = 1.2
          setTimeout(() => {
            this.scale = 1
          }, 300)
        })
      
      Text(`当前评分: ${this.rating}`)
        .fontSize(16)
        .margin(10)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

五、注意事项

1. 性能考虑：

   • 避免在频繁变化的组件中使用复杂的Rating样式
   • 大量Rating组件时考虑使用轻量级实现

2. 用户体验：

   • 常用star数量为5或10
   • 步长0.5(半星)或1(整星)最符合用户习惯
   • 提供明确的评分指引文字

3. 样式适配：

   • 在不同设备上测试Rating的显示效果
   • 考虑深色/浅色模式下的颜色适配

4. 交互反馈：

   • 评分变化时提供视觉或触觉反馈
   • 重要评分操作可增加确认步骤

Rating组件是鸿蒙系统中非常实用的评分输入控件，通过灵活使用各种API可以实现多样化的评分需求。根据具体场景选择合适的配置方式。