鸿蒙 ArkTS 实战：Class Score Average 从成绩平均计算到成绩统计应用完整解析
鸿蒙 ArkTS 实战：Class Score Average 从成绩平均计算到成绩统计应用完整解析
前言
成绩平均计算 是一个典型的鸿蒙 ArkTS 轻量工具页面。它围绕“维护一组成绩数组，选择单项调整分数并实时计算平均分，还可以新增 90 分记录。”这个明确需求，把参数输入、公式计算、状态反馈和结果展示集中在同一屏。
本文基于 Class Score Average 的真实源码展开，重点分析@State 状态建模、Slider 数值输入、Toggle 开关状态、ForEach 列表渲染、方法封装公式和条件样式反馈。
工具型应用的关键不是页面复杂，而是输入变化后结果足够清楚、足够及时。
图示说明：页面由标题摘要、参数控制、结果展示和业务说明组成，适合学习 ArkTS 单页工具的状态流。
一、项目场景
1.1 业务目标
维护一组成绩数组，选择单项调整分数并实时计算平均分，还可以新增 90 分记录。
1.2 用户路径
- 查看默认参数和初始结果。
- 通过滑杆、按钮、开关或列表调整输入。
- 页面立即重新计算并展示结果。
- 用户根据结果完成估算、计划或记录。
1.3 技术目标
| 目标 | 页面体现 | ArkTS 实现 |
|---|---|---|
| 参数输入 | 数字、开关、选项 | Slider / Toggle / ForEach |
| 状态保存 | 当前数值和选择 | @State |
| 公式计算 | 税额、重量、费用、平均值 | 方法封装 |
| 结果反馈 | 大数字和状态文案 | Text / Stack / 条件样式 |
二、页面入口
2.1 组件骨架
@Entry@Componentstruct Index{build(){Column(){Text('成绩平均计算')}}}2.2 单页结构价值
成绩平均计算 的主要状态是 scores、selected。这些字段都直接影响界面输出，集中在一个组件中更利于理解数据流。
2.3 页面分区
| 区域 | 作用 | 常见组件 |
|---|---|---|
| 顶部 | 标题和核心结果 | Row、Text |
| 中部 | 图形结果或列表 | Stack、Circle、ForEach |
| 底部 | 参数和说明 | Slider、Button、Toggle |
三、状态建模
3.1 State 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| scores | number[] | 成绩数组，默认 92、88、95、79、84 |
| selected | number | 当前选中的成绩索引 |
3.2 状态声明
@Entry@Componentstruct Index{@Statescores:number[]=[92,88,95,79,84];// 成绩数组，默认 92、88、95、79、84@Stateselected:number=0;// 当前选中的成绩索引}3.3 状态边界
这些字段都贴近业务语言。数值字段用于计算，布尔字段用于开关，索引字段用于选择，数组字段用于可变列表。
状态字段越接近用户看到的业务概念，后续调试就越轻松。
四、业务数据
4.1 静态配置
scores：92、88、95、79、84
4.2 列表渲染
ForEach(this.items,(item:string,index:number)=>{Text(item).fontSize(16).fontWeight(FontWeight.Bold).onClick(()=>{this.selected=index})})4.3 选中态表达
.backgroundColor(this.selected===index?'#2563EB':'#FFFFFF').fontColor(this.selected===index?'#FFFFFF':'#2563EB')这种写法可以让当前选择、详情内容和视觉高亮保持同步。
五、输入控件
5.1 Slider 数值输入
Slider 适合调节金额、天数、宽度、体重、分钟、比例、株距和成绩等范围参数。
Slider({value:this.value,min:0,max:100,step:1}).onChange((value:number)=>{this.value=Math.round(value)})5.2 Toggle 开关
Toggle 用于含税、提醒、专注模式等二值状态。
Toggle({type:ToggleType.Switch,isOn:this.enabled}).onChange((on:boolean)=>{this.enabled=on})5.3 Button 操作
Button 用于新增、确认、重置或推进离散动作。
Button('执行').backgroundColor('#2563EB').onClick(()=>{this.count+=1})六、交互行为
6.1 动作列表
- ForEach 渲染成绩列表
- 点击行切换 selected
- Slider 调整当前成绩
- avg 方法遍历数组求平均
- 按钮向 scores 追加 90 分
6.2 关键源码
avg():number{letsum:number=0for(leti=0;i<this.scores.length;i++){sum+=this.scores[i]}returnMath.round(sum/this.scores.length)}6.3 反馈闭环
- ForEach 渲染成绩列表
- 点击行切换 selected
- Slider 调整当前成绩
- avg 方法遍历数组求平均
- 按钮向 scores 追加 90 分
交互闭环很简单：用户改变输入，状态字段更新，公式重新计算，Text 和颜色同步刷新。
七、公式解析
7.1 核心公式
avg=round(sum(scores)/scores.length)7.2 方法封装
当公式包含判断、循环或取整时，用方法封装更清楚。
privatecalc():number{returnMath.round(1)}7.3 结果渲染
Text('结果：'+String(value)).fontSize(40).fontWeight(FontWeight.Bold).fontColor('#2563EB')结果必须配合单位展示，避免用户误解数字含义。
八、视觉设计
8.1 大数字
税额、天数、码数、克数、金额、分钟、毫升、厘米、公里、分数等都适合用大字号强调。
8.2 图形容器
Stack、Circle、Rect 能让结果区域更集中。
Stack(){Circle().width(200).height(200).fill('#F8FAFC')Text('核心结果')}8.3 条件颜色
.fontColor(this.warning?'#DC2626':'#2563EB')8.4 文案提示
Text(this.done?'已完成':'待处理')九、布局策略
9.1 上下结构
上下结构适合先展示标题和结果，再展示参数控制。
9.2 左右结构
左右结构适合左侧大结果、右侧参数列表的工具页面。
9.3 信息层级
| 层级 | 内容 | 目的 |
|---|---|---|
| 一级 | 核心结果 | 直接判断 |
| 二级 | 输入参数 | 明确来源 |
| 三级 | 说明文案 | 解释规则 |
十、调试路径
10.1 手动验证
- 检查默认状态是否与源码一致。
- 调整每个 Slider 或 Toggle。
- 确认公式结果即时刷新。
- 测试最小值、最大值和开关状态。
10.2 日志辅助
Button('调试').onClick(()=>{console.info('state changed')})10.3 问题定位
| 问题 | 原因 | 处理方式 |
|---|---|---|
| 结果不变 | 状态未写回 | 检查 onChange |
| 数字异常 | 公式边界未处理 | 增加取整或限制 |
| 文案不对 | 条件分支错误 | 单独验证布尔值 |
| 列表错位 | index 映射错误 | 对齐数组顺序 |
十一、工程扩展
11.1 历史记录
可以保存每一次估算、换算、计划或统计结果，方便后续对比。
interfaceHistoryItem{title:stringinput:stringresult:stringcreatedAt:string}11.2 本地缓存
用户经常重复使用同一组参数，适合把最近一次状态缓存起来。
11.3 分享结果
{"tool":"成绩平均计算","state":"scores、selected","result":"calculated"}十二、体验优化
12.1 单位清晰
元、天、码、克、分钟、毫升、厘米、公里、分数等单位必须紧跟结果。
12.2 范围合理
Slider 的 min、max、step 要符合真实使用场景。
12.3 反馈直接
工具页面不应该等提交后再展示结果，输入变化后就应立即刷新。
十三、完整片段
13.1 状态骨架
@Entry@Componentstruct Index{@Statescores:number[]=[92,88,95,79,84];// 成绩数组，默认 92、88、95、79、84@Stateselected:number=0;// 当前选中的成绩索引}13.2 数据配置
// scores：92、88、95、79、84privateprimaryColor:string='#2563EB'13.3 交互代码
avg():number{letsum:number=0for(leti=0;i<this.scores.length;i++){sum+=this.scores[i]}returnMath.round(sum/this.scores.length)}13.4 样式代码
Text('核心结果').fontSize(28).fontWeight(FontWeight.Bold).fontColor('#2563EB')十四、复用价值
14.1 状态复用
- number 用于金额、天数、重量、比例和分数。
- boolean 用于提醒、含税和专注等开关。
- number[] 可用于成绩、清单和多项统计。
14.2 公式复用
成绩平均计算 的公式写法可以迁移到更多换算、预算、规划和统计页面。
14.3 组件复用
结果卡片、参数滑杆、选择标签和说明文案都可以抽成通用组件。
十五、发布级拆解
15.1 场景先行
文章开头先说清楚 成绩平均计算 解决什么问题，再进入 ArkTS 代码，读者更容易理解公式意义。
15.2 状态为线索
围绕 scores、selected 展开讲解，可以把页面输入、计算和结果串起来。
15.3 公式落地
公式avg = round(sum(scores) / scores.length)是本项目的核心技术点，应同时解释输入来源、计算过程和输出展示。
15.4 边界意识
工具页要关注极值、开关变化、数组索引和除法取整，避免用户调整参数后出现异常结果。
十六、总结
Class Score Average 用简洁的 ArkTS 页面完成了 成绩统计 场景。它围绕 scores、selected 建模，结合 scores：92、88、95、79、84 组织输入，并通过avg = round(sum(scores) / scores.length)把业务规则转换成即时可见的结果。
这类鸿蒙小工具的关键在于：状态清楚、公式透明、反馈及时、边界稳定。理解这个项目后，再开发税额计算、倒计日、尺寸换算、喂食计算、费用估算或成绩统计等页面都会更顺手。
相关资源：
- HarmonyOS 开发者官网
- ArkTS 语言指南
- ArkUI 开发框架