harmony 鸿蒙Rating

2025-06-12
浏览 (3)

Rating

提供在给定范围内选择评分的组件。

说明：

该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

Rating(options?: RatingOptions)

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	RatingOptions	否	设置评分组件。

属性

stars

stars(value: number)

设置评分总数。设置为小于等于0的值时，按默认值显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	设置评分总数。默认值：5

stars¹⁸⁺

stars(starCount: Optional<number>)

设置评分总数。设置为小于等于0的值时，按默认值显示。与stars相比，starCount参数新增了对undefined类型的支持。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
starCount	Optional<number>	是	设置评分总数。当starCount的值为undefined时，默认值：5

stepSize

stepSize(value: number)

设置操作评级的步长。设置为小于0.1的值时，按默认值显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	操作评级的步长。默认值：0.5 取值范围：[0.1, stars]

stepSize¹⁸⁺

stepSize(size: Optional<number>)

设置操作评级的步长。设置为小于0.1的值时，按默认值显示。与stepSize相比，size参数新增了对undefined类型的支持。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
size	Optional<number>	是	操作评级的步长。当size的值为undefined时，默认值：0.5 取值范围：[0.1, stars]

starStyle

starStyle(options: StarStyleOptions)

设置评分的样式。该属性所支持的图片类型能力参考Image组件。

支持加载本地图片和网络图片，暂不支持PixelMap类型。

默认图片加载方式为异步，暂不支持同步加载。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	StarStyleOptions	是	评分的样式。说明：当backgroundUri、foregroundUri或secondaryUri设置的图片路径错误时，图片将不显示。当backgroundUri或foregroundUri设置为undefined或空字符串时，Rating组件将加载系统默认星型图源。当secondaryUri未设置或设置为undefined或空字符串时，将优先使用backgroundUri，效果等同于仅设置foregroundUri和backgroundUri。

starStyle¹⁸⁺

starStyle(options: Optional<StarStyleOptions>)

设置评分的样式。该属性所支持的图片类型能力参考Image组件。

支持加载本地图片和网络图片，暂不支持PixelMap类型。

默认图片加载方式为异步，暂不支持同步加载。

与starStyle相比，options参数新增了对undefined类型的支持。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	Optional<StarStyleOptions>	是	评分的样式。说明：当backgroundUri、foregroundUri或secondaryUri设置的图片路径错误时，图片将不显示。当backgroundUri或foregroundUri设置为undefined或空字符串时，Rating组件将加载系统默认星型图源。当secondaryUri未设置或设置为undefined或空字符串时，将优先使用backgroundUri，效果等同于仅设置foregroundUri和backgroundUri。

说明：

当Rating组件的宽高为[width, height]时，单个图片的绘制区域为[width / stars, height]。

为确保绘制区域为方形，建议自定义宽高时采用[height * stars, height]，即width = height * stars的方式。

contentModifier¹²⁺

contentModifier(modifier: ContentModifier<RatingConfiguration>)

定制Rating内容区的方法。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	ContentModifier<RatingConfiguration>	是	在Rating组件上，定制内容区的方法。 modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。

contentModifier¹⁸⁺

contentModifier(modifier: Optional>)

定制Rating内容区的方法。与contentModifier相比，modifier参数新增了对undefined类型的支持。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	Optional<ContentModifier<RatingConfiguration>>	是	在Rating组件上，定制内容区的方法。 modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。当modifier的值为undefined时，不使用内容修改器。

事件

onChange

onChange(callback:(value: number) => void)

当评分条的评星变化时触发该回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number	是	评分条的评分。

onChange¹⁸⁺

onChange(callback:Optional<OnRatingChangeCallback>)

当评分条的评星变化时触发该回调。与onChange相比，callback参数新增了对undefined类型的支持。

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	Optional<OnRatingChangeCallback>	是	操作评分条的评星变化时触发该回调。当callback的值为undefined时，不使用回调函数。

OnRatingChangeCallback¹⁸⁺

type OnRatingChangeCallback = (rating: number) => void

操作评分条的评星变化时触发该回调。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
rating	number	是	评分条的评分。

键盘走焦规格

按键	功能描述
Tab	组件间切换焦点。
左右方向键	评分预览增加/减少（步长为step），不改变实际分值。
Home	移动到第一个星星，不改变实际分值。
End	移动到最后一个星星，不改变实际分值。
Space/Enter	根据当前评分提交评分结果。

RatingConfiguration¹²⁺对象说明

开发者需要自定义class实现ContentModifier接口。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	只读	可选	说明
rating	number	否	否	设置并接收评分值。默认值：0 取值范围： [0, stars] 小于0取0，大于stars取最大值stars。该参数支持$$双向绑定变量。该参数支持!!双向绑定变量。
indicator	boolean	否	否	评分条是否作为指示器使用。当值为true时，表示作为指示器；当值为false时，表示不作为指示器。默认值：false
stars	number	否	否	评分条的星级总数。默认值：5
stepSize	number	否	否	评分条的评分步长。默认值：0.5
triggerChange	Callback<number>	否	否	触发评分数量变化。

RatingOptions¹⁸⁺对象说明

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
rating⁷⁺	number	是	设置并接收评分值。默认值：0 取值范围： [0, stars] 小于0取0，大于stars取最大值stars。该参数支持$$双向绑定变量。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
indicator⁷⁺	boolean	否	设置评分组件作为指示器使用，值为true时，不可改变评分。默认值：false，可进行评分说明： indicator=true时，默认组件高度height=12.0vp，组件width=height * stars。 indicator=false时，默认组件高度height=28.0vp，组件width=height * stars。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。

StarStyleOptions¹⁸⁺对象说明

卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。

原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

名称	类型	必填	说明
backgroundUri⁷⁺	ResourceStr	是	未选中的星级的图片链接，可由用户自定义或使用系统默认图片。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。从API version 20开始，该接口支持设置Resource资源。参考示例4（通过Resource资源设置评分的样式）代码。
foregroundUri⁷⁺	ResourceStr	是	选中的星级的图片路径，可由用户自定义或使用系统默认图片。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。从API version 20开始，该接口支持设置Resource资源。参考示例4（通过Resource资源设置评分的样式）代码。
secondaryUri⁷⁺	ResourceStr	否	部分选中的星级的图片路径，可由用户自定义或使用系统默认图片。卡片能力：从API version 9开始，该接口支持在ArkTS卡片中使用。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。从API version 20开始，该接口支持设置Resource资源。参考示例4（通过Resource资源设置评分的样式）代码。

说明：

string格式可用于加载网络图片和本地图片。当使用相对路径引用本地图片时，例如Image(“common/test.jpg”)，其中common目录与pages同级，同时支持Base64字符串。

示例

示例1（设置默认评分样式）

以下示例展示了如何创建默认星型评分样式。

// xxx.ets
@Entry
@Component
struct RatingExample {
  @State rating: number = 3.5;

  build() {
    Column() {
      Column() {
        Rating({ rating: this.rating, indicator: false })
          .stars(5)
          .stepSize(0.5)
          .margin({ top: 24 })
          .onChange((value: number) => {
            this.rating = value;
          })
        Text('current score is ' + this.rating)
          .fontSize(16)
          .fontColor('rgba(24,36,49,0.60)')
          .margin({ top: 16 })
      }.width(360).height(113).backgroundColor('#FFFFFF').margin({ top: 68 })

      Row() {
        Image('common/testImage.jpg')
          .width(40)
          .height(40)
          .borderRadius(20)
          .margin({ left: 24 })
        Column() {
          Text('Yue')
            .fontSize(16)
            .fontColor('#182431')
            .fontWeight(500)
          Row() {
            Rating({ rating: 3.5, indicator: false }).margin({ top: 1, right: 8 })
            Text('2021/06/02')
              .fontSize(10)
              .fontColor('#182431')
          }
        }.margin({ left: 12 }).alignItems(HorizontalAlign.Start)

        Text('1st Floor')
          .fontSize(10)
          .fontColor('#182431')
          .position({ x: 295, y: 8 })
      }.width(360).height(56).backgroundColor('#FFFFFF').margin({ top: 64 })
    }.width('100%').height('100%').backgroundColor('#F1F3F5')
  }
}

rating

示例2（设置评分的样式）

以下示例展示了如何通过配置starStyle实现自定义星级的图片链接。

// xxx.ets
@Entry
@Component
struct RatingExample {
  @State rating: number = 3.5;

  build() {
    Column() {
      Rating({ rating: this.rating, indicator: false })
        .stars(5)
        .stepSize(0.5)
        .starStyle({
          backgroundUri: '/common/imag1.png', // common目录与pages同级
          foregroundUri: '/common/imag2.png',
          secondaryUri: '/common/imag3.png'
        })
        .margin({ top: 24 })
        .onChange((value: number) => {
          this.rating = value;
        })
      Text('current score is ' + this.rating)
        .fontSize(16)
        .fontColor('rgba(24,36,49,0.60)')
        .margin({ top: 16 })
    }.width('100%').height('100%').backgroundColor('#F1F3F5')
  }
}

rating1

示例3（自定义评分条）

以下示例实现了自定义评分条的功能，其中每个圆圈表示0.5分。当ratingIndicator为true时，评分条作为指示器使用，不可改变评分；当为false时，可进行评分。ratingStars用于设置评分总数，ratingStepsize用于设置评分步长。

// xxx.ets
class MyRatingStyle implements ContentModifier<RatingConfiguration> {
  name: string = "";
  style: number = 0;

  constructor(value1: string, value2: number) {
    this.name = value1;
    this.style = value2;
  }

  applyContent(): WrappedBuilder<[RatingConfiguration]> {
    return wrapBuilder(buildRating);
  }
}

@Builder
function buildRating(config: RatingConfiguration) {
  Column() {
    Row() {
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 0.4 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            if (config.stepSize = 0.5) {
              config.triggerChange(0.5);
              return
            }
            if (config.stepSize = 1) {
              config.triggerChange(1);
              return
            }
          }
        }).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden)
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 0.9 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            config.triggerChange(1);
          }
        }).visibility(config.stars >= 1 ? Visibility.Visible : Visibility.Hidden)
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 1.4 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            if (config.stepSize = 0.5) {
              config.triggerChange(1.5);
              return
            }
            if (config.stepSize = 1) {
              config.triggerChange(2);
              return
            }
          }
        }).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden).margin({ left: 10 })
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 1.9 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            config.triggerChange(2);
          }
        }).visibility(config.stars >= 2 ? Visibility.Visible : Visibility.Hidden)
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 2.4 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            if (config.stepSize = 0.5) {
              config.triggerChange(2.5);
              return
            }
            if (config.stepSize = 1) {
              config.triggerChange(3);
              return
            }
          }
        }).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden).margin({ left: 10 })
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 2.9 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            config.triggerChange(3);
          }
        }).visibility(config.stars >= 3 ? Visibility.Visible : Visibility.Hidden)
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 3.4 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            if (config.stepSize = 0.5) {
              config.triggerChange(3.5);
              return
            }
            if (config.stepSize = 1) {
              config.triggerChange(4);
              return
            }
          }
        }).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden).margin({ left: 10 })
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 3.9 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            config.triggerChange(4);
          }
        }).visibility(config.stars >= 4 ? Visibility.Visible : Visibility.Hidden)
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 4.4 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            if (config.stepSize = 0.5) {
              config.triggerChange(4.5);
              return
            }
            if (config.stepSize = 1) {
              config.triggerChange(5);
              return
            }
          }
        }).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden).margin({ left: 10 })
      Circle({ width: 25, height: 25 })
        .fill(config.rating >= 4.9 ? Color.Black : Color.Red)
        .onClick((event: ClickEvent) => {
          if (!config.indicator) {
            config.triggerChange(5);
          }
        }).visibility(config.stars >= 5 ? Visibility.Visible : Visibility.Hidden)
    }

    Text("分值：" + config.rating)
  }
}

@Entry
@Component
struct ratingExample {
  @State rating: number = 0;
  @State ratingIndicator: boolean = true;
  @State ratingStars: number = 0;
  @State ratingStepsize: number = 0.5;
  @State ratingEnabled: boolean = true;

  build() {
    Row() {
      Column() {
        Rating({
          rating: 0,
          indicator: this.ratingIndicator
        })
          .stepSize(this.ratingStepsize)
          .stars(this.ratingStars)
          .backgroundColor(Color.Transparent)
          .width('100%')
          .height(50)
          .onChange((value: number) => {
            console.info('Rating change is' + value);
            this.rating = value;
          })
          .contentModifier(new MyRatingStyle("hello", 3))
        Button(this.ratingIndicator ? "ratingIndicator : true" : "ratingIndicator : false")
          .onClick((event) => {
            if (this.ratingIndicator) {
              this.ratingIndicator = false;
            } else {
              this.ratingIndicator = true;
            }
          }).margin({ top: 5 })

        Button(this.ratingStars < 5 ? "ratingStars + 1, ratingStars =" + this.ratingStars : "ratingStars最大值为5")
          .onClick((event) => {
            if (this.ratingStars < 5) {
              this.ratingStars += 1;
            }
          }).margin({ top: 5 })

        Button(this.ratingStars > 0 ? "ratingStars - 1, ratingStars =" + this.ratingStars :
          "ratingStars小于等于0时默认等于5")
          .onClick((event) => {
            if (this.ratingStars > 0) {
              this.ratingStars -= 1;
            }
          }).margin({ top: 5 })

        Button(this.ratingStepsize == 0.5 ? "ratingStepsize : 0.5" : "ratingStepsize : 1")
          .onClick((event) => {
            if (this.ratingStepsize == 0.5) {
              this.ratingStepsize = 1;
            } else {
              this.ratingStepsize = 0.5;
            }
          }).margin({ top: 5 })
      }
      .width('100%')
      .height('100%')
      .justifyContent(FlexAlign.Center)
    }
    .height('100%')
  }
}

rating2

示例4（通过Resource资源设置评分的样式）

该示例通过Resource资源配置starStyle，实现自定义星级图片链接。

// xxx.ets
@Entry
@Component
struct RatingExample {
  @State rating: number = 3.5;

  build() {
    Column() {
      Rating({ rating: this.rating, indicator: false })
        .stars(5)
        .stepSize(0.5)
        .starStyle({
          backgroundUri: $r('app.media.imag1'),
          foregroundUri: $r('app.media.imag2'),
          secondaryUri: $r('app.media.imag3')
        })
        .margin({ top: 24 })
        .onChange((value: number) => {
          this.rating = value;
        })
      Text('current score is ' + this.rating)
        .fontSize(16)
        .fontColor('rgba(24,36,49,0.60)')
        .margin({ top: 16 })
    }.width('100%').height('100%').backgroundColor('#F1F3F5')
  }
}

rating1

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙弹出框 (Dialog)

harmony 鸿蒙DialogV2

0 赞

所属分类： 后端技术
本文标签：
版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/JT2uU3

harmony 鸿蒙Rating

Rating

子组件

接口

属性

stars

stars¹⁸⁺

stepSize

stepSize¹⁸⁺

starStyle

starStyle¹⁸⁺

contentModifier¹²⁺

contentModifier¹⁸⁺

事件

onChange

onChange¹⁸⁺

OnRatingChangeCallback¹⁸⁺

键盘走焦规格

RatingConfiguration¹²⁺对象说明

RatingOptions¹⁸⁺对象说明

StarStyleOptions¹⁸⁺对象说明

示例

示例1（设置默认评分样式）

示例2（设置评分的样式）

示例3（自定义评分条）

示例4（通过Resource资源设置评分的样式）

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

harmony 鸿蒙Rating

Rating

子组件

接口

属性

stars

stars18+

stepSize

stepSize18+

starStyle

starStyle18+

contentModifier12+

contentModifier18+

事件

onChange

onChange18+

OnRatingChangeCallback18+

键盘走焦规格

RatingConfiguration12+对象说明

RatingOptions18+对象说明

StarStyleOptions18+对象说明

示例

示例1（设置默认评分样式）

示例2（设置评分的样式）

示例3（自定义评分条）

示例4（通过Resource资源设置评分的样式）

你可能感兴趣的鸿蒙文章

热门推荐

标签云

最新文章

本文目录

stars¹⁸⁺

stepSize¹⁸⁺

starStyle¹⁸⁺

contentModifier¹²⁺

contentModifier¹⁸⁺

onChange¹⁸⁺

OnRatingChangeCallback¹⁸⁺

RatingConfiguration¹²⁺对象说明

RatingOptions¹⁸⁺对象说明

StarStyleOptions¹⁸⁺对象说明