HarmonyOS7 RatingStepPrecision 教程：整数、半星与四分之一星评分

前言

当评分开始追求更细腻的表达时，stepSize 就成了必须理解的参数。它直接决定用户一次能给出多精细的结果。 这也是我很喜欢拿来讲 ArkUI 的一类例子，因为它足够小，却能把状态、布局和反馈三件事串起来。 这篇更适合边读边对照代码，因为很多细节只有放在页面行为里才看得出来。

这篇我会重点从动画与反馈设计这个角度往下讲。不是为了把每个属性都讲一遍，而是帮你建立一个更接近真实开发的阅读顺序：先看页面目标，再看状态流，最后再看样式怎么收口。

适用场景

读这段代码时，先看用户会做什么，再看代码为什么这样写，会顺很多。

把它放进真实项目里看，会更容易理解这个案例的价值。围绕“Rating 步长”这件事，页面通常不是孤立存在的，它前面连着输入动作，后面连着结果展示。

这一类写法常见在 商品评价、内容评分、门店口碑、榜单展示 这些页面里。你只要把示例里的交互换成自己的业务文案，再把静态数据换成真实数据源，骨架基本就够用了。

我读这类示例时有个习惯：先不看属性名，先看“用户碰了哪里，页面发生了什么”。这样更容易抓住重点。

另外一个不能跳过的问题是边界。这个案例要是准备落地，第一时间要检查的通常不是样式，而是 状态字段和展示结果有没有保持同一份数据来源，避免页面看起来“能动”但结果不可信。

实现思路

页面最外层通常先用Column把主轴定下来，这一步看起来普通，但它决定了后面所有内容是顺着读，还是碎着看。

如果代码里出现了Scroll，那基本说明作者已经预判到内容会超过一屏。这种处理很实在，至少不会等页面做长了再返工。

这一页更多是纵向阅读逻辑，说明作者希望用户按顺序完成操作，而不是在多个区域来回跳。

第 5 篇案例在布局上最值得学的地方，是它没有为了展示组件能力去强行堆内容，而是尽量让每一块区域都有明确职责。这样的代码后面更好拆组件。

完整代码

下面这份代码保留了案例本身的实现思路，但把示例编号替换成了更自然的英文命名。你直接拿去做实验、拆段运行，阅读成本会低很多。

/** * RatingStepPrecision - Rating 步长 */import{PRESET_COLORS,generateListItems,PAGE_BG_COLOR,PANEL_BG_COLOR,ACCENT_COLOR,MUTED_TEXT_COLOR}from'./types'@Entry@Componentstruct RatingStepPrecision{@StateisShow:boolean=true@StateratingFull:number=3@StateratingHalf:number=2.5@StateratingQuarter:number=3.75build(){Column(){if(this.isShow){Scroll(){Column(){Text('Rating 步长 (stepSize)').fontSize(16).fontWeight(FontWeight.Bold).margin({bottom:16})Text('stepSize=1 整数评分').fontSize(14).fontWeight(FontWeight.Medium).margin({bottom:8})Rating({rating:this.ratingFull,indicator:false}).stars(5).stepSize(1).onChange((v:number)=>{this.ratingFull=v})Text(`${this.ratingFull.toFixed(0)}星`).fontSize(14).fontColor(ACCENT_COLOR).margin({top:4,bottom:16})Text('stepSize=0.5 半星评分').fontSize(14).fontWeight(FontWeight.Medium).margin({bottom:8})Rating({rating:this.ratingHalf,indicator:false}).stars(5).stepSize(0.5).onChange((v:number)=>{this.ratingHalf=v})Text(`${this.ratingHalf.toFixed(1)}星`).fontSize(14).fontColor(ACCENT_COLOR).margin({top:4,bottom:16})Text('stepSize=0.25 细粒度评分').fontSize(14).fontWeight(FontWeight.Medium).margin({bottom:8})Rating({rating:this.ratingQuarter,indicator:false}).stars(5).stepSize(0.25).onChange((v:number)=>{this.ratingQuarter=v})Text(`${this.ratingQuarter.toFixed(2)}星`).fontSize(14).fontColor(ACCENT_COLOR).margin({top:4})}.width('100%').padding(16).backgroundColor(PANEL_BG_COLOR).borderRadius(12).alignItems(HorizontalAlign.Center)}}Text('Rating 步长 - stepSize 1/0.5/0.25 精度').fontSize(12).fontColor(MUTED_TEXT_COLOR).margin({top:12})}.width('100%').height('100%').backgroundColor(PAGE_BG_COLOR).padding(16)}}

逐段读代码

第一处关键代码

@State isShow: boolean = true

这一行先别急着略过，它通常就是页面状态的起点。后面很多显示内容，都会跟着它一起变化。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。

第二处关键代码

@State ratingFull: number = 3

看起来只是一个字段定义，但页面后面能不能“动起来”，很多时候就靠它。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。

第三处关键代码

@State ratingHalf: number = 2.5

这种状态声明的价值，不在写法本身，而在于它决定了谁来保存结果、谁来触发刷新。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。

容易忽略的细节

这段代码里，真正驱动页面活起来的，多半是下面这些位置：

• .onChange((v: number) => { this.ratingFull = v })
• .onChange((v: number) => { this.ratingHalf = v })
• .onChange((v: number) => { this.ratingQuarter = v })

对评分类页面来说，页面顺不顺手，往往取决于用户点完之后有没有马上看到数值和文案一起变。

这里最值得养成的习惯，是顺手确认结果值到底存在哪。状态一多，页面最容易出的问题不是不刷新，而是刷出来的不是同一个结果。

真准备继续往下改时，我会先把输入值、结果值和提示文案拆开存。这样后面无论是加校验还是加动画，都不容易把build()变成大杂烩。

再往前走一步

真要把这个案例拿去改业务页面，我会按下面这个顺序动手：

• 把演示用的静态数据替换成真实数据源，别等接口接进来以后再改页面结构。
• 把重复出现的卡片、标题栏、结果区提成小组件，后面加状态会轻松很多。
• 提前补上异常态，比如空值、失败态、禁用态、超范围输入，否则示例一进业务就会露怯。
• 如果是评分页，我会尽量把“用户可评分”和“只展示结果”拆开，不让一个组件同时承担两种语义。

这里最容易被忽略的一点，是 状态字段和展示结果有没有保持同一份数据来源，避免页面看起来“能动”但结果不可信。 这个问题。很多示例在静态数据下看不出毛病，一接真实状态就开始暴露问题，所以这一步最好趁早做。

容易被忽略的小地方

有些细节在第一眼看代码时很容易被跳过去，但它们往往决定了页面是不是耐改。

• @State不是装饰器样板，它决定了哪些数据变化后会重新驱动画面。
• 对于 Rating 类页面，我会特别留意文案反馈是不是跟着用户动作一起变化，因为这直接影响页面有没有“会说话”的感觉。

这些东西单看都不复杂，组合在一起，才是一个案例真正的完成度。

写在最后

把这篇读透之后，你再回头看同类控件，会更容易判断哪些是核心参数，哪些只是表面样式。

把这份案例读成“一个可以继续长大的页面骨架”，你后面改业务时会轻松很多。