HarmonyOS6 ArkTS Rating组件使用文档

完整代码

// RatingFullExample.ets @Entry @Component struct RatingFullExample { // 评分值 @State score: number = 3.5; // 是否为只读指示器 @State isIndicator: boolean = false; // 星星总数 @State starCount: number = 5; // 评分步长 @State step: number = 0.5; build() { Column({ space: 25 }) { Text("Rating 评分组件完整示例") .fontSize(26) .fontWeight(FontWeight.Bold) .margin({ top: 30 }); // 1. 默认评分组件 Column({ space: 12 }) { Text("1. 默认五星评分（步长0.5）") .fontSize(18) .alignSelf(ItemAlign.Start); Rating({ rating: this.score, indicator: this.isIndicator }) .stars(this.starCount) .stepSize(this.step) .onChange((value: number) => { this.score = value; console.info("当前评分：" + value); }) .width(300) .height(40); Text(`当前得分：${this.score.toFixed(1)}`) .fontSize(16) .fontColor("#007DFF"); } .width("90%") .padding(15) .backgroundColor("#F5F5F5") .borderRadius(12); // 2. 控制区 Column({ space: 15 }) { Text("2. 功能控制") .fontSize(18) .alignSelf(ItemAlign.Start); // 切换只读指示器 Row({ space: 10 }) { Text("只读模式（指示器）：") .fontSize(16); Toggle({ type: ToggleType.Switch, isOn: this.isIndicator }) .onChange((val) => { this.isIndicator = val; }); } // 步长切换 Row({ space: 10 }) { Text("评分步长：") .fontSize(16); Button(this.step === 0.5 ? "0.5（半星）" : "1.0（整星）") .onClick(() => { this.step = this.step === 0.5 ? 1.0 : 0.5; }) .width(140); } // 星星数量 Row({ space: 10 }) { Text("星星数量：") .fontSize(16); Button(`星星数：${this.starCount}`) .onClick(() => { this.starCount = this.starCount >= 10 ? 5 : this.starCount + 1; }) .width(120); } } .width("90%") .padding(15) .backgroundColor("#F5F5F5") .borderRadius(12); // 3. 自定义样式评分（使用系统默认样式，可替换图片） Column({ space: 12 }) { Text("3. 自定义样式评分") .fontSize(18) .alignSelf(ItemAlign.Start); Rating({ rating: this.score, indicator: false }) .stars(5) .stepSize(0.5) .starStyle({ backgroundUri: "", // 未选中星（空则使用系统默认） foregroundUri: "", // 选中星（空则使用系统默认） secondaryUri: "" // 半星（可选） }) .onChange((value) => { this.score = value; }) .width(300) .height(40); } .width("90%") .padding(15) .backgroundColor("#F5F5F5") .borderRadius(12); } .width("100%") .padding(10) .backgroundColor("#fff") } }

运行效果如图：

核心参数与方法

1 组件构造参数

2 核心属性方法（链式调用）

（1）星星数量设置：stars

• 类型：number
• 说明：设置评分组件的星星总数，默认值为 5
• 示例：.stars(this.starCount)

（2）评分步长设置：stepSize

• 类型：number
• 说明：设置评分最小间隔，支持0.5（半星）和1.0（整星）
• 示例：.stepSize(this.step)

（3）星级样式自定义：starStyle

• 类型：RatingStyle
• 说明：配置星级图标资源，属性为空时使用系统默认图标
  | 属性名 | 说明 |
  |--------|------|
  | backgroundUri | 未选中星级图标路径 |
  | foregroundUri | 选中星级图标路径 |
  | secondaryUri | 半星图标路径（可选） |
• 示例：

.starStyle({ backgroundUri: "", foregroundUri: "", secondaryUri: "" })

（4）评分变化回调：onChange

• 回调参数：value: number（当前选中的评分值）
• 说明：用户滑动/点击评分时触发，可实时更新评分数据、打印日志
• 示例：

.onChange((value: number) => { this.score = value; console.info("当前评分：" + value); })

核心变量

运行效果

1. 默认评分区域：初始化展示 5 颗星星，默认评分 3.5，支持半星选择，下方实时显示当前得分；
2. 功能控制区域：
   • 开关开启后，评分组件变为只读模式，无法点击/滑动修改评分；
   • 按钮可切换0.5 半星和1.0 整星两种步长；
   • 点击按钮可递增星星数量，达到 10 颗后重置为 5 颗；
3. 自定义样式区域：使用系统默认星级图标，可通过填写图标路径替换为自定义样式，评分状态与全局评分同步；
4. 所有操作触发的评分变化，均会实时更新页面数据，并在控制台打印评分日志。

总结

1 适用场景

• 用户评价、商品评分、服务打分等可交互评分场景；
• 个人等级、商家评分、作品评分等只读展示场景；
• 配置类页面、个性化设置中的星级选择场景。

2 使用规范

1. 交互模式：需要用户主动评分时，设置indicator: false；仅用于展示分数时，设置indicator: true；
2. 步长选择：追求精细评分使用 0.5 步长，简约评分使用 1.0 步长；
3. 样式规范：自定义图标需保持尺寸一致，避免星星显示错位；
4. 数据绑定：必须使用状态变量绑定评分，保证数据响应式更新。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力