一、引言星级评分是移动端应用中最常见的交互组件之一。从 App Store 的应用评分、豆瓣的电影打分到电商平台的商品评价——五颗星不仅是数字的视觉化表达更是用户情绪的快捷传递方式。在 HarmonyOS NEXT 之前开发者若要实现星级评分需要手动绘制 5 个 Image 组件、管理点击区域、计算分数——代码零散且容易出 Bug。ArkUI 在 API 10 中新增了Rating组件将星级评分的所有逻辑封装为一个独立组件只需一行声明就能获得支持交互式评分、只读展示、半星精度和自定义样式的完整评分体验。本文通过一个影片评分 Demo深入讲解 Rating 组件的核心用法如何区分交互式评分和只读展示如何设置半星精度如何自定义星星样式以及如何在实际业务场景中将 Rating 融入用户交互流程。阅读完本文你将能够使用Rating组件替代手工绘制的星级评分区分indicator: true只读和indicator: false交互式两种模式用stepSize控制评分精度1 整星0.5 半星用starStyle自定义星星的前景、背景和次要图标将 Rating 组件的onChange事件融入真实的业务数据流二、Rating 组件 API 总览2.1 构造函数参数Rating({rating:0,indicator:false})参数类型说明ratingnumber初始评分值范围0到stars默认 5。默认为 0无星indicatorboolean是否为指示器模式。true 只读展示不可交互false 可交互评分rating是外部传入的值Rating 组件本身不会自动维护内部评分状态——它始终反映从外部传入的rating值。这意味着开发者需要自己维护评分状态并在onChange回调中更新。indicator是 Rating 组件最关键的开关true星星纯粹是视觉展示用户点击和滑动都无效。适用于显示社区平均评分历史评分记录等场景。false用户可以通过点击星星来改变评分。适用于用户打分当前评分等交互场景。2.2 属性方法stars(count: number)设置星星的总数默认为 5。Rating({rating:3}).stars(5)// 5颗星默认值可省略虽然可以设置任意星数如 10但 5 星是行业标准——App Store、豆瓣、亚马逊等主流平台均使用 5 星制。偏离这个标准会让用户感到困惑因此不推荐修改。stepSize(value: number)设置评分的最小变化步长.stepSize(1)// 仅支持整数评分0, 1, 2, 3, 4, 5.stepSize(0.5)// 支持半星评分0, 0.5, 1, 1.5, ..., 5stepSize(1)是默认值用户只能给出整数星。这在快速评价场景中足够用5 选 1。stepSize(0.5)开启半星支持用户可以给出 3.5 星这样的分数。半星的重要场景是展示精确的平均分——比如豆瓣电影 4.2 分半星能精确到一位小数信息量比只有整数星高出一倍。步长值为 1 时的实际行为用户点击第 3 颗星 → 分数变为 3用户点击第 2 和第 3 颗星之间 → 分数仍为 3因为步长限制为整数。starStyle(options: StarStyle)自定义星星的图标样式.starStyle({backgroundUri:,// 未选中状态的星星图标foregroundUri:,// 选中状态的星星图标secondaryUri:// 半选状态的星星图标})三个 URI 分别控制不同状态的星星外观。如果都不传留空字符串使用系统默认的黄色五角星。自定义 URI 可以是网络图片或本地资源路径。本 Demo 使用默认样式——系统原生星星在各种主题和屏幕上都有一致的外观。2.3 事件回调onChange(callback: (value: number) void)评分变化时触发。用户每次点击星星在非 indicator 模式下value即为新的评分值。Rating({rating:movie.myRating,indicator:false}).onChange((v:number){this.rateMovie(movie.title,v);})onChange只在交互式模式indicator: false下有效。只读模式不会触发该回调因为用户无法改变评分。三、Demo 设计影片评分页3.1 功能概述Demo 模拟一个影片评分页面包含 4 部电影。每张电影卡片展示两组 Rating豆瓣评分只读半星精度stepSize: 0.5展示社区平均分如 4.2 分橙色文字 评分数显示我的评分交互式整星精度stepSize: 1用户可点击打星紫色文字 评分后显示X星4 部电影覆盖不同的评分区间3.7 到 4.6让用户能够在多种场景下观察 Rating 的只读展示效果。3.2 数据结构interfaceMovieItem{title:string;// 电影名year:string;// 上映年份genre:string;// 类型desc:string;// 简介color:string;// 海报占位色avgRating:number;// 社区平均分只读展示totalRatings:number;// 评分数myRating:number;// 用户评分交互式评分}4 部电影按avgRating从高到低排列电影豆瓣均分评分人数哪吒之魔童闹海4.635.6 万流浪地球 34.218.5 万长安三万里3.912.4 万飞驰人生 33.79.8 万3.3 两种 Rating 模式的对比应用每张电影卡片中两组 Rating 同时存在但扮演不同角色只读模式的实现Rating({rating:movie.avgRating,indicator:true}).stars(5).stepSize(0.5).width(120).height(22)indicator: true→ 不可交互纯粹展示社区评分stepSize(0.5)→ 半星精度精确展示 4.2、3.7 等平均值width(120)/height(22)→ 控制星星所占空间与文字标签对齐只用 120vp 宽的 Rating 就能传递这部电影口碑很好的视觉信息——4.2 分显示为 4 颗满星 1/5 颗半星。视图尺寸小巧适合放在信息展示区域而非操作区域。交互式模式的实现Rating({rating:movie.myRating,indicator:false}).stars(5).stepSize(1).width(160).height(30).onChange((v:number){this.rateMovie(movie.title,v);})indicator: false→ 可交互用户点击改变评分stepSize(1)→ 仅整星用户快速选择 1-5 星width(160)/height(30)→ 比只读模式更大因为交互需要更大的触控区域onChange→ 评分变化时更新数据和 UI交互式评分区分于只读展示的三个设计要点更大160vp vs 120vp为手指点击提供足够的触控面积更高30vp vs 22vp避免星星太矮导致误触更反馈右侧文字实时显示3星4星等评分结果紫色加粗强调3.4 评分回调与状态更新rateMovie(title:string,rating:number):void{constnewMovies:MovieItem[][];for(leti0;ithis.movies.length;i){constmthis.movies[i];if(m.titletitle){newMovies.push({title:m.title,year:m.year,genre:m.genre,desc:m.desc,color:m.color,avgRating:m.avgRating,totalRatings:m.totalRatings,myRating:rating});}else{newMovies.push(m);}}this.moviesnewMovies;}不可变数组更新模式——遍历 4 部电影只修改目标电影的myRating字段其余保持不变。新数组整体赋值给State movies触发 UI 刷新。评分完成后展示 Toast 确认this.ratedMovietitle;this.showToasttrue;consttidsetInterval((){clearInterval(tid);this.showToastfalse;},2000);Toast 通过Stack的position({ bottom: 80 })定位在页面底部中央setInterval在 2 秒后自动消失。这不是 Rating 组件的功能而是对评分成功这一业务事件的视觉确认——让用户知道自己的评分已被记录。3.5 页面结构┌─────────────────────────────────────┐ │ ⭐ 影片评分深色标题栏 │ ├─────────────────────────────────────┤ │ Rating 组件说明卡片 │ ├─────────────────────────────────────┤ │ ┌───────────────────────────────┐ │ │ │ 哪吒之魔童闹海 │ │ │ │ 2025 · 动画/奇幻 │ │ │ │ 魔丸转世的哪吒在成长中... │ │ │ │ │ │ │ │ 豆瓣评分 ★★★★½ 4.6 分 (35.6万)│ │ ← 只读 Rating │ │ ───────────────────────────── │ │ │ │ 我的评分 ★★★★☆ 4星 │ │ ← 交互式 Rating │ └───────────────────────────────┘ │ │ ┌───────────────────────────────┐ │ │ │ 流浪地球 3 │ │ │ │ ...同样结构 │ │ │ └───────────────────────────────┘ │ ├─────────────────────────────────────┤ │ [✓ 评分成功]Toast2秒后消失 │ └─────────────────────────────────────┘四、Rating 组件的视觉规格4.1 默认星星样式系统默认的 Rating 星星使用以下视觉方案未选中星灰色空心五角星#E0E0E0左右选中星金黄色实心五角星#FFC107左右半星左半黄色实心 右半灰色空心这个默认样式与 Material Design 和 iOS 的评分组件视觉一致——用户无需学习就能理解含义。4.2 尺寸与间距星星的默认尺寸由组件的width和height属性决定。如果width和height未显式设置Rating 使用默认尺寸约 24vp × 24vp 的单星大小。在实践中推荐显式设置width和height只读模式.width(120).height(22)—— 紧凑适合信息展示区交互模式.width(160).height(30)—— 宽松提供更大的触控目标5 颗星之间的间距由组件自动计算总宽度除以星数开发者不需要手动设置间距。4.3 自定义星星图标starStyle的三个 URI 参数允许替换默认的五角星.starStyle({backgroundUri:app.media.empty_star,// 资源目录中的空星图片foregroundUri:app.media.filled_star,// 资源目录中的满星图片secondaryUri:app.media.half_star// 半星图片仅在 stepSize0.5 时显示})URI 格式支持app.media.xxx应用资源目录resources/base/media/中的图片http(s)://...网络图片需申请网络权限空字符串使用系统默认样式在实际项目中自定义星星图标最常见的场景是品牌定制——例如一家旅游 App 可能想用棕榈树图标替代星星一家美食 App 可能想用叉子图标。starStyle使得这种定制变得简单——只需替换三张图不需要修改 Rating 的任何逻辑代码。五、Rating 的最佳实践5.1 何时使用 indicator 模式indicator: true适用于展示第三方数据的场景电商平台的商品评分4.7 分基于 2.3 万条评价App Store 的应用评分餐厅/酒店的平均评分历史评分记录用户之前给过的评分这些场景的共同特征是评分数据来自外部数据库/API用户只能看不能改。使用 indicator 模式可以防止用户误触改变评分同时保持视觉一致性。5.2 何时使用 stepSize(0.5)半星精度stepSize: 0.5适用于信息密集型展示展示精确到一位小数的平均分如 4.2、3.8数据可视化面板对比图表半星不应该用于用户交互式评分——让用户在 0-5 的 11 个选项0, 0.5, 1, …, 5中选择是过于精细的决策增加了不必要的认知负担。交互式评分建议使用stepSize(1)6 个选项简洁明了。5.3 尺寸选择使用场景推荐 width推荐 height理由只读展示紧凑100-12018-22信息密度高不占用过多空间只读展示突出140-18024-28强调评分数据如商品详情页顶部交互式评分150-20028-36需要更大的触控区域减少误触5.4 与文字标签的配合Rating 组件本身不显示数字分数——它是纯粹的视觉表现。在实际应用中Rating 通常与文字标签配合使用★★★★☆ 4.2 分 (18.5 万评价)三者形成完整的评分信息视觉Rating快速传递大约多少分一眼识别 4 星数值Text精确传递具体多少分4.2 这个数字基数Text传递有多少人打分18.5 万人更具说服力在 Demo 中这三者在一条 Row 中水平排列Rating → 分数数字 → 评价人数。三者的文字颜色依次从醒目到柔化橙色 → 灰色形成视觉层级。六、完整代码结构RatingPage (~200 行) ├── 数据定义 │ └── MovieItem 接口 — 7 字段含 avgRating 和 myRating ├── 状态变量 │ ├── State movies[4] — 4 部电影数据 │ └── State showToast — Toast 显隐 ├── 业务逻辑 │ └── rateMovie() — 不可变更新 myRating Toast 弹出 ├── 视图 │ ├── 标题栏 — ⭐ 影片评分 │ ├── 说明卡片 — Rating 组件介绍 │ ├── 4 张电影卡片ForEach │ │ ├── 海报占位 电影信息 │ │ ├── 只读 Rating豆瓣评分stepSize0.5 │ │ └── 交互式 Rating我的评分stepSize1 onChange │ └── Toast 浮层条件渲染 Stack.position └── 生命周期 └── aboutToAppear() — 初始化 4 部电影数据七、总结本文通过一个影片评分 Demo深入讲解了 HarmonyOS NEXT 中的Rating 星级评分组件。Rating 将传统的手工绘制星星逻辑封装为标准组件通过indicator开关区分只读和交互两种模式通过stepSize控制评分精度通过starStyle支持自定义图标样式。核心要点回顾Rating 的双模式indicator: true创建只读展示适用于社区评分、历史记录indicator: false创建交互式评分适用于用户打分。同一个组件的两个模式共享相同的视觉语言但在交互行为上完全隔离。stepSize 控制精度stepSize(1) 仅整星快速选择适用于用户打分stepSize(0.5) 半星精度精确展示适用于数据可视化。两种精度服务于不同的业务场景不应混用。starStyle 自定义图标通过backgroundUri空星、foregroundUri满星、secondaryUri半星三个 URI 参数可以将默认的黄色五角星替换为任意自定义图标。这在品牌定制场景中非常实用。onChange 与状态管理Rating 不维护内部评分状态——它始终反映外部传入的rating值。开发者需要在onChange回调中手动更新评分并通过不可变数组模式触发 UI 刷新。这种受控组件模式保证了评分状态与业务数据的一致性。Rating 与文字的配合视觉星星→ 数值数字→ 基数评价人数三者形成完整的评分信息链。视觉占比最大Rating 组件的 120-200vp数值用颜色强调橙色/紫色基数用浅色弱化灰色 11sp。Rating 组件是 HarmonyOS NEXT 中小而美的典型代表——它的 API 只有 3 个方法 1 个事件但通过参数组合可以覆盖从简单评分到复杂数据可视化的所有场景。这种简单接口 灵活组合的设计哲学正是 ArkUI 声明式组件体系的核心优势。