鸿蒙 ArkTS 实战：Training Checkin Tool 从专业流程到完成闭环完整解析

鸿蒙 ArkTS 实战：Training Checkin Tool 从专业流程到完成闭环完整解析

前言

Training Checkin Tool 是一个面向培训签到工具场景的鸿蒙 ArkTS 单页应用。它没有把重点放在复杂后台能力上，而是围绕一线人员最常见的记录、统计、提醒和完成确认构建移动端工作台。

这类应用的价值在于把签到人数、备注信息和完成状态放到同一屏，减少纸质登记、聊天转述和临时表格之间的切换。本文会结合项目中的Index.ets，从数据模型、状态管理、统计逻辑、表单录入、列表渲染和扩展方向完整拆解。

场景判断：课程开始前后签到变化快，缺勤统计和导出动作如果滞后，会影响教务跟进。

图示说明：本文关注的是 Training Checkin Tool 这类轻量工具应用的页面状态、业务记录和交互闭环。

一、项目定位与业务目标

1.1 面向的真实业务

项目服务于 培训机构对早晚班级签到人数、缺勤提醒和统计导出进行管理。使用者主要包括培训老师、教务、校区运营，他们对系统的要求通常不是功能堆叠，而是打开即用、信息集中、状态明确。

工具用班级记录承载签到人数、缺勤备注和完成状态，适合课前快速核对。 这也是该项目选择单页结构的核心原因。

1.2 页面能力拆分

当前页面可以拆成四个层次：

1. 顶部标题，用来确认正在处理的业务类型。

2. 统计区域，用Checkins和Done表示总量与完成度。

3. 功能标签区域，用四个短标签压缩业务能力。

4. 表单与列表区域，用于新增记录、展示备注、切换完成状态。

二、工程结构与入口文件

2.1 关键目录

项目采用标准鸿蒙 Stage 工程结构，业务页面位于entry/src/main/ets/pages/Index.ets。单页工具型应用的优势是路径清晰，阅读成本低，后续扩展时也容易把模型、组件和服务逐步拆出去。

entry/ src/ main/ ets/ entryability/ EntryAbility.ets pages/ Index.ets module.json5

2.2 模块配置关注点

模块配置负责声明入口 Ability 和资源范围。文章讨论的业务逻辑主要集中在页面层，但理解模块结构有助于定位运行入口。

{"module":{"name":"entry","type":"entry","srcEntry":"./ets/Application/AbilityStage.ts","abilities":[{"name":"EntryAbility","srcEntry":"./ets/entryability/EntryAbility.ets","exported":true}]},"articleTopic":"培训签到工具"}

这一层不直接参与业务计算，却决定应用如何被系统加载。对单页工具而言，保持配置简洁可以减少排查路径。

三、数据模型设计

3.1 记录对象的最小闭环

Training Checkin Tool 的每条业务记录由title、amount、note、done四个字段构成。这个模型非常克制，但已经覆盖了列表工具的核心闭环：是什么、数量多少、有什么备注、是否完成。

interfaceProRecord{title:string;amount:number;note:string;done:boolean;}@Staterecords:ProRecord[]=[{title:'Morning class',amount:28,note:'3 absent alerts',done:false},{title:'Evening class',amount:16,note:'Stats export ready',done:false}];

3.2 默认数据的业务含义

项目内置了两条默认记录，方便首次打开页面时直接看到业务样例，也能验证统计区和列表区是否联动正常。

这两条数据不是随意占位，而是围绕学生名单、扫码签到、缺勤提醒和统计导出四个业务点设计。

四、状态管理与输入缓存

4.1 页面状态字段

页面使用@State保存记录列表、三个输入框内容、提醒开关和状态文案。所有字段都直接参与界面刷新，因此适合放在组件状态中。

@StatetitleText:string='';@StateamountText:string='';@StatenoteText:string='';@StatenotifyOn:boolean=true;@Statestatus:string='Professional workflow ready';

4.2 为什么输入框独立保存

标题、数量、备注分别保存在titleText、amountText、noteText中，避免用户输入过程直接污染记录列表。只有点击按钮并通过校验后，才会生成新的记录。

关键点：表单草稿和正式记录分离，可以降低误写入概率，也让状态文案有明确的反馈位置。

五、统计逻辑：总量与完成度

5.1 总量统计

totalAmount()遍历 records，把每条记录的 amount 累加。对于本项目来说，它代表Checkins的当前总数，也就是页面顶部最醒目的业务指标。

5.2 完成数量统计

doneCount()只统计done为 true 的记录，并以完成数/总记录数的方式展示，让用户快速判断剩余处理压力。

privatetotalAmount():number{lettotal=0;this.records.forEach((item:ProRecord)=>{total+=item.amount;});returntotal;}privatedoneCount():number{letcount=0;this.records.forEach((item:ProRecord)=>{if(item.done){count++;}});returncount;}

六、表单新增记录

6.1 校验规则

新增记录时先把数量字符串转换为数字，再检查标题是否为空、数量是否有效。校验失败时，页面会把状态文案改为Enter title and valid number。

6.2 新记录插入到顶部

通过数组展开语法把新记录放到旧列表前面，这样最新任务会出现在最上方，符合现场工作台的使用习惯。

privateaddRecord():void{constamount=Number(this.amountText);if(this.titleText.trim().length===0||!Number.isFinite(amount)){this.status='Enter title and valid number';return;}this.records=[{title:this.titleText,amount:Math.round(amount),note:this.noteText.length>0?this.noteText:'No note yet',done:false},...this.records];this.titleText='';this.amountText='';this.noteText='';this.status='Record added';}

在 培训签到工具 场景里，新记录通常比历史记录更需要优先处理，因此顶部插入比尾部追加更适合移动端快速操作。

七、完成状态切换

7.1 勾选逻辑

完成状态通过 checkbox 触发。代码先修改指定索引的done字段，再使用数组展开生成新引用，确保 UI 能感知 records 的变化。

privatetoggleDone(index:number):void{this.records[index].done=!this.records[index].done;this.records=[...this.records];}

7.2 状态驱动视觉反馈

记录完成后，列表项背景会从白色切换为浅绿色。这个视觉变化比单纯文字更直接，适合一线人员在忙碌环境中快速扫描。

八、页面布局与信息层级

8.1 统计卡片

顶部两张统计卡片分别表达总量和完成度，颜色也做了区分：蓝色强调数量，绿色强调完成状态。

Row({space:10}){Column({space:4}){Text('Checkins').fontSize(13).fontColor('#475569')Text(String(this.totalAmount())).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#1D4ED8')}.layoutWeight(1).padding(14).backgroundColor('#DBEAFE').borderRadius(8)Column({space:4}){Text('Done').fontSize(13).fontColor('#475569')Text(this.doneCount()+'/'+this.records.length).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#047857')}.layoutWeight(1).padding(14).backgroundColor('#D1FAE5').borderRadius(8)}

8.2 功能标签

页面中的四个标签分别是Student list、QR checkin、Absence alert、Stats export。它们不是按钮，而是能力提示，用来让使用者快速确认这个工具覆盖哪些工作环节。

功能标签对应到中文业务，可以理解为：

• 学生名单：确认记录主体。

• 扫码签到：补充关键过程信息。

• 缺勤提醒：让任务不会沉没。

• 统计导出：为后续交接保留依据。

九、输入区域与列表渲染

9.1 输入区域

表单区采用三个输入框加一个按钮的结构，字段少、路径短，适合移动端单手录入。数量输入框使用InputType.Number，降低录入非数字内容的概率。

Column({space:10}){TextInput({placeholder:'Title',text:this.titleText}).onChange((value:string)=>this.titleText=value)TextInput({placeholder:'Number',text:this.amountText}).type(InputType.Number).onChange((value:string)=>this.amountText=value)TextInput({placeholder:'Note',text:this.noteText}).onChange((value:string)=>this.noteText=value)Button('Add record').height(42).width('100%').onClick(()=>this.addRecord())}

9.2 列表区域

列表使用ForEach根据 records 渲染。每行左侧是完成勾选，中间是标题和备注，右侧是数量，信息密度较高但不会混乱。

ForEach(this.records,(item:ProRecord,index:number)=>{Row(){Toggle({type:ToggleType.Checkbox,isOn:item.done}).onChange(()=>this.toggleDone(index))Column({space:6}){Text(item.title).fontSize(18).fontWeight(FontWeight.Bold).fontColor('#111827')Text(item.note).fontSize(14).fontColor('#475569')}.layoutWeight(1).margin({left:8})Text(String(item.amount)).fontSize(18).fontWeight(FontWeight.Bold).fontColor('#1D4ED8')}.padding(14).backgroundColor(item.done?'#DCFCE7':'#FFFFFF').borderRadius(8).width('100%')})

这个布局非常适合 培训签到工具：标题承载对象，备注承载现场上下文，数量承载统计口径，勾选承载工作闭环。

十、业务流程复盘

10.1 从录入到完成

结合项目代码，Training Checkin Tool 的一次完整业务流可以分为四步：

1. 录入班级。

2. 填写签到人数。

3. 备注缺勤或导出状态。

4. 核对完成后勾选。

10.2 异常路径

当标题为空或数量无效时，新增动作不会写入列表，而是更新状态文案。这个处理虽然简单，但避免了空记录进入正式列表。

constamount=Number(this.amountText);constinvalid=this.titleText.trim().length===0||!Number.isFinite(amount);if(invalid){this.status='Enter title and valid number';}

十一、体验细节与可维护性

11.1 低成本可维护

项目没有引入额外状态库，页面逻辑都在组件内部完成。对于这类轻量工具，简单结构反而有利于交付和维护。

11.2 可扩展边界

后续可以接入二维码签到、家长通知和出勤率趋势图。

扩展时可以遵循下面顺序：

1. 先把记录模型从页面拆到独立文件。

2. 再增加本地持久化，保证关闭应用后数据不丢失。

3. 最后接入网络同步、权限和多端协同。

interfacePersistedRecord{id:string;title:string;amount:number;note:string;done:boolean;updatedAt:number;}

十二、调试与验证思路

12.1 手动验证路径

验证时重点看三件事：新增记录是否在顶部出现、统计总量是否变化、勾选后完成比例和背景色是否同步更新。

12.2 边界输入

边界输入包括空标题、非数字数量、负数、超大数量和空备注。当前代码已经拦截空标题和非数字，空备注会自动使用No note yet。

# DevEco Studio 中可执行的常规验证动作# 1. 启动预览或真机运行# 2. 输入标题和数量# 3. 点击 Add record# 4. 勾选列表项观察 Done 统计

十三、适合复用的页面模式

13.1 通用记录台

Training Checkin Tool 的实现可以抽象成通用记录台：一个数组、三个输入字段、两个统计函数、一个新增函数、一个完成切换函数。许多门店、培训、医疗、仓储类小工具都可以复用这个模式。

13.2 适配更多行业

只要把默认数据、统计名称、功能标签和业务文案替换掉，就能变成另一个行业的小工具。真正需要谨慎处理的是字段语义和统计口径，不能只改标题。

复用公式： 业务对象 + 数量口径 + 备注上下文 + 完成状态 = 可闭环的移动工作台

总结

Training Checkin Tool 用非常克制的 ArkTS 实现，完成了培训签到工具场景中的核心闭环：记录任务、统计数量、补充备注、切换完成状态。它的代码重点不在复杂算法，而在业务信息组织方式。

对于 培训老师、教务、校区运营 来说，这种轻量工具的关键价值是减少切换、降低漏处理概率，并把当天工作沉淀成清晰列表。后续如果接入本地持久化、提醒能力和行业字段，这个项目就能从演示型页面继续成长为可落地的小型业务应用。

如果这篇文章对你有帮助，可以点赞、收藏并关注，后续会继续拆解更多鸿蒙 ArkTS 实战项目。

相关资源：

• HarmonyOS 应用开发
• ArkTS 语言基础
• ArkUI 声明式开发
• DevEco Studio
• 应用包结构
• Ability Kit
• CSDN 写作平台
• Markdown 基础语法