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

前言

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

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

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

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

一、项目定位与业务目标

1.1 面向的真实业务

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

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

1.2 页面能力拆分

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

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

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

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

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

能力区域	项目实现	业务含义
统计卡片	totalAmount / doneCount	统计签到人数和完成数量
功能标签	四个 Text 标签	明确页面覆盖的业务点
录入表单	三个 TextInput	采集标题、数量和备注
记录列表	ForEach 渲染	展示任务并支持勾选

二、工程结构与入口文件

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 四个字段构成。这个模型非常克制，但已经覆盖了列表工具的核心闭环：是什么、数量多少、有什么备注、是否完成。

interface ProRecord {
  title: string;
  amount: number;
  note: string;
  done: boolean;
}

@State records: 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 默认数据的业务含义

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

默认标题	数量	备注	完成状态
Morning class	28	3 absent alerts	false
Evening class	16	Stats export ready	false

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

四、状态管理与输入缓存

4.1 页面状态字段

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

@State titleText: string = '';
@State amountText: string = '';
@State noteText: string = '';
@State notifyOn: boolean = true;
@State status: string = 'Professional workflow ready';

4.2 为什么输入框独立保存

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

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

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

5.1 总量统计

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

5.2 完成数量统计

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

private totalAmount(): number {
  let total = 0;
  this.records.forEach((item: ProRecord) => {
    total += item.amount;
  });
  return total;
}

private doneCount(): number {
  let count = 0;
  this.records.forEach((item: ProRecord) => {
    if (item.done) {
      count++;
    }
  });
  return count;
}

方法	输入	输出	页面位置
totalAmount	records.amount	Checkins	左侧统计卡片
doneCount	records.done	Done 比例	右侧统计卡片
toggleDone	记录索引	完成状态变更	列表勾选框

六、表单新增记录

6.1 校验规则

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

6.2 新记录插入到顶部

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

private addRecord(): void {
  const amount = 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 的变化。

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

7.2 状态驱动视觉反馈

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

状态	背景色	用户感知
未完成	#FFFFFF	仍需处理
已完成	#DCFCE7	可以归档或跳过
输入异常	状态文案提示	需要修正标题或数量

八、页面布局与信息层级

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 异常路径

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

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

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

11.1 低成本可维护

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

11.2 可扩展边界

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

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

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

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

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

interface PersistedRecord {
  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 统计

验证项	预期结果	业务意义
新增有效记录	列表顶部出现新行	现场可以快速追加任务
空标题提交	显示错误状态	避免无效记录
勾选完成	Done 统计变化	形成完成闭环
备注为空	使用默认备注	保持列表信息完整

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

13.1 通用记录台

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

13.2 适配更多行业

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

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

总结

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

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

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

---

相关资源：

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