文章目录
-
- 前言
- 为什么这个例子值得单独看
- 页面是怎么跑起来的
- 完整代码
- 拆开三段关键实现
-
- 第一处关键代码
- 第二处关键代码
- 第三处关键代码
- 改成业务代码时要补什么
-
- 再往前走一步
- 容易被忽略的小地方
- 写在最后
前言
综合案例最适合拿来做知识归纳，因为读者能在一个页面里同时看到多种能力的差异。 我更关心的不是它能不能跑，而是它跑起来之后，用户会不会觉得顺手。 你可以把这篇当成一次真实页面拆解，而不是一份孤立的组件笔记。
这篇我会重点从 交互状态管理 这个角度往下讲。不是为了把每个属性都讲一遍，而是帮你建立一个更接近真实开发的阅读顺序：先看页面目标，再看状态流，最后再看样式怎么收口。
为什么这个例子值得单独看
如果你是第一次接触这个控件，别急着把每个属性都背下来，先看它解决了什么交互问题。
“Rating 综合演示”这种能力，单独演示时很轻，落到项目里却往往要和表单、列表、卡片或者反馈区绑在一起，这也是这个案例值得细看的原因。
这一类写法常见在 商品评价、内容评分、门店口碑、榜单展示 这些页面里。你只要把示例里的交互换成自己的业务文案，再把静态数据换成真实数据源，骨架基本就够用了。
示例读不明白时，最好的办法不是多看几遍属性表，而是先把页面里的角色关系搞明白。
如果你后面要把示例改成线上页面，别急着先美化，先确认 状态字段和展示结果有没有保持同一份数据来源，避免页面看起来“能动”但结果不可信。
页面是怎么跑起来的
页面最外层通常先用 Column 把主轴定下来，这一步看起来普通，但它决定了后面所有内容是顺着读，还是碎着看。
如果代码里出现了 Scroll，那基本说明作者已经预判到内容会超过一屏。这种处理很实在，至少不会等页面做长了再返工。
像 Row 这种并排容器，真正的价值不是“能横着排”，而是帮你把对比关系直接摆给用户看。数字、标签、刻度、按钮放在一起时，理解速度会快很多。
第 12 篇案例在布局上最值得学的地方，是它没有为了展示组件能力去强行堆内容，而是尽量让每一块区域都有明确职责。这样的代码后面更好拆组件。
完整代码
下面这份代码保留了案例本身的实现思路，但把示例编号替换成了更自然的英文命名。你直接拿去做实验、拆段运行，阅读成本会低很多。
/**
* RatingWorkbench – Rating 综合演示
*/
import { PRESET_COLORS, generateListItems, PAGE_BG_COLOR, PANEL_BG_COLOR, ACCENT_COLOR, MUTED_TEXT_COLOR } from './types'
@Entry
@Component
struct RatingWorkbench {
@State isShow: boolean = true
@State rating1: number = 3
@State rating2: number = 4.5
@State rating3: number = 0
build() {
Column() {
if (this.isShow) {
Scroll() {
Column() {
Text('Rating 综合演示').fontSize(16).fontWeight(FontWeight.Bold).margin({ bottom: 16 })
Text('1. 可交互评分 (stepSize=1)').fontSize(14).fontWeight(FontWeight.Bold).margin({ bottom: 6 })
Row({ space: 10 }) {
Rating({ rating: this.rating1, indicator: false }).stars(5).stepSize(1)
.onChange((v: number) => { this.rating1 = v })
Text(`${this.rating1.toFixed(0)}/5`).fontSize(14).fontColor(ACCENT_COLOR)
}.margin({ bottom: 20 })
Text('2. 半星评分 (stepSize=0.5)').fontSize(14).fontWeight(FontWeight.Bold).margin({ bottom: 6 })
Row({ space: 10 }) {
Rating({ rating: this.rating2, indicator: false }).stars(5).stepSize(0.5)
.onChange((v: number) => { this.rating2 = v })
Text(`${this.rating2.toFixed(1)}/5`).fontSize(14).fontColor(ACCENT_COLOR)
}.margin({ bottom: 20 })
Text('3. 可交互评分 (stars=10)').fontSize(14).fontWeight(FontWeight.Bold).margin({ bottom: 6 })
Row({ space: 10 }) {
Rating({ rating: this.rating3, indicator: false }).stars(10)
.onChange((v: number) => { this.rating3 = v })
Text(`${this.rating3.toFixed(0)}/10`).fontSize(14).fontColor(ACCENT_COLOR)
}.margin({ bottom: 20 })
Text('4. 只读展示 (indicator)').fontSize(14).fontWeight(FontWeight.Bold).margin({ bottom: 8 })
ForEach([1.5, 2.5, 3.5, 4.5, 5.0], (r: number, idx: number) => {
Row() {
Text(`评分 ${r}`).fontSize(13).width(55)
Rating({ rating: r, indicator: true }).stars(5)
}.margin({ bottom: 6 })
})
}
.width('100%').padding(16).backgroundColor(PANEL_BG_COLOR).borderRadius(12)
}
}
Text('Rating 综合 – 交互/半星/多星/只读')
.fontSize(12).fontColor(MUTED_TEXT_COLOR).margin({ top: 12 })
}
.width('100%').height('100%').backgroundColor(PAGE_BG_COLOR).padding(16)
}
}
拆开三段关键实现
第一处关键代码
@State isShow: boolean = true
这一行先别急着略过，它通常就是页面状态的起点。后面很多显示内容，都会跟着它一起变化。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。
第二处关键代码
@State rating1: number = 3
看起来只是一个字段定义，但页面后面能不能“动起来”，很多时候就靠它。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。
第三处关键代码
@State rating2: number = 4.5
这种状态声明的价值，不在写法本身，而在于它决定了谁来保存结果、谁来触发刷新。 如果这是评分相关代码，我还会继续追一下它最终有没有同步到展示文案或结果区。
改成业务代码时要补什么
很多人第一次读示例会从头到尾扫一遍，但更高效的做法，其实是先看下面这些触发点：
- .onChange((v: number) => { this.rating1 = v })
- .onChange((v: number) => { this.rating2 = v })
- .onChange((v: number) => { this.rating3 = v })
- ForEach([1.5, 2.5, 3.5, 4.5, 5.0], (r: number, idx: number) => {
对评分类页面来说，页面顺不顺手，往往取决于用户点完之后有没有马上看到数值和文案一起变。
读到交互段时，不妨多问一句：这个结果有没有唯一数据源？很多页面后面难维护，就是从这里埋下的。
一个很实用的改法，是尽早把状态分层：谁负责输入，谁负责展示，谁负责兜底。只要这一步做清楚，后面页面再长，build() 也不至于越来越乱。
再往前走一步
真要把这个案例拿去改业务页面，我会按下面这个顺序动手：
- 把演示用的静态数据替换成真实数据源，别等接口接进来以后再改页面结构。
- 把重复出现的卡片、标题栏、结果区提成小组件，后面加状态会轻松很多。
- 提前补上异常态，比如空值、失败态、禁用态、超范围输入，否则示例一进业务就会露怯。
- 如果是评分页，我会尽量把“用户可评分”和“只展示结果”拆开，不让一个组件同时承担两种语义。
这里最容易被忽略的一点，是 状态字段和展示结果有没有保持同一份数据来源，避免页面看起来“能动”但结果不可信。 这个问题。很多示例在静态数据下看不出毛病，一接真实状态就开始暴露问题，所以这一步最好趁早做。
容易被忽略的小地方
有些细节在第一眼看代码时很容易被跳过去，但它们往往决定了页面是不是耐改。
- @State 不是装饰器样板，它决定了哪些数据变化后会重新驱动画面。
- 看到 ForEach 时，顺手检查一下列表项是不是结构稳定、职责单一，这会直接影响后续抽组件的成本。
- 对于 Rating 类页面，我会特别留意文案反馈是不是跟着用户动作一起变化，因为这直接影响页面有没有“会说话”的感觉。
这些东西单看都不复杂，组合在一起，才是一个案例真正的完成度。
写在最后
真正有用的不是把例子抄下来，而是知道下一次写相似页面时，自己应该先搭哪一层。这个案例刚好提供了一个很稳的起点。
如果你只打算先改一处，我建议先改状态流，因为它决定后面所有交互是不是顺手。
