鸿蒙 ArkTS 实战：Stall Payment Ledger 从业务记录到移动工作台完整解析

前言

Stall Payment Ledger 是一个面向摊位收款台账的鸿蒙 ArkTS 单页应用。它的实现并不追求复杂后台，而是把一线业务里最常见的记录、数量统计、备注和完成状态放到一个移动工作台中。

项目适用于 移动摊主记录单品销售、收款方式、库存扣减和每日收摊结算。对于夜市摊主、快闪店店员、市集运营者来说，核心目标是减少临时纸条、聊天转发和表格补录，把当天任务沉淀成可追踪的列表。

业务痛点：摊位销售常常同时涉及现金、扫码收款和库存变化，事后补账容易丢失细节。

图示说明：本文围绕 Stall Payment Ledger 的页面状态、业务记录、统计卡片和交互闭环展开。

一、业务定位与页面目标

1.1 解决什么问题

用简洁台账记录销售金额、支付方式和库存变化，让小摊经营也能形成清楚的日结依据。 这类小工具的关键不是功能数量，而是把一个高频动作做短、做稳、做清楚。

1.2 页面能力概览

当前页面主要由四部分组成：

1. 顶部标题，确认工具所属业务场景。

2. 统计卡片，展示Daily sales与 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","abilities":[{"name":"EntryAbility","srcEntry":"./ets/entryability/EntryAbility.ets","exported":true}]},"topic":"摊位收款台账"}

三、数据模型：四个字段完成闭环

3.1 记录结构

项目使用ToolRecord描述一条业务记录。title表示任务主体，amount表示数量口径，note保存上下文，done表示是否完成。

interfaceToolRecord{title:string;amount:number;note:string;done:boolean;}@Staterecords:ToolRecord[]=[{title:'Lemon tea sale',amount:168,note:'WeChat pay, stock -12',done:false},{title:'Keychain sale',amount:96,note:'Cash, daily close ready',done:false}];

3.2 默认记录分析

默认记录用于表达项目的真实业务方向，同时也能在首次运行时验证统计和列表渲染是否正常。

这些默认数据分别触达商品销售、收款方式、库存扣减和日结收摊，不是空泛占位。

四、状态管理设计

4.1 页面状态字段

页面把 records、输入框草稿、提醒开关和状态文案都放在@State中。它们变化后会驱动 UI 重新渲染，适合轻量页面直接管理。

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

4.2 草稿和正式记录分离

三个输入框先写入草稿状态，只有点击新增并通过校验后才进入 records。这样可以避免用户输入一半时影响正式列表。

关键点：移动端工具越简单，越要保证数据进入列表前经过明确动作和基础校验。

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

5.1 总量统计

totalAmount()遍历 records，把 amount 累加为Daily sales。它是顶部左侧卡片的数据来源。

5.2 完成统计

doneCount()统计 done 为 true 的记录数量，并与总记录数拼接显示。这个指标能快速反映任务推进情况。

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

六、新增记录流程

6.1 输入校验

新增时先把数量转换为数字，再判断标题是否为空、数量是否有效。无效输入不会进入正式列表。

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 触发完成状态切换。代码修改对应记录后，重新展开数组生成新引用，从而稳定触发刷新。

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('Daily sales').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 业务标签解读

四个标签分别是Product sale、Payment method、Stock decrease、Daily close。它们帮助用户快速理解工具覆盖的业务范围。

• 商品销售：确认记录对象。

• 收款方式：明确执行计划。

• 库存扣减：处理异常或提醒。

• 日结收摊：保留交接依据。

九、表单与列表渲染

9.1 表单区域

表单由标题、数字、备注三个输入框组成，配合一个新增按钮完成最短路径录入。

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(this.records,(item:ToolRecord,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 标准路径

Stall Payment Ledger 的业务闭环可以拆成四步：

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 模型拆分

当业务继续增长时，可以把记录模型拆到独立文件，并增加 id、时间戳和来源字段。

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

11.2 行业扩展

后续可以增加支付方式筛选、商品库存表和日销售曲线。

扩展顺序可以保持为：

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

2. 增加行业字段，让记录更贴近真实业务。

3. 增加导出、提醒或同步能力，支撑团队协作。

十二、调试与验证

12.1 核心验证点

验证时重点观察新增记录、统计变化、完成勾选和异常输入四类路径。

12.2 运行检查

可以在 DevEco Studio 中启动预览或真机运行，按业务流程逐项验证交互是否符合预期。

# 常规验证动作# 1. 输入标题、数量和备注# 2. 点击 Add record# 3. 检查新记录是否位于顶部# 4. 勾选记录并观察 Done 统计

十三、可复用的工具应用模式

13.1 通用公式

这个项目可以抽象为一个通用模式：业务对象、数量口径、备注上下文、完成状态。很多线下管理工具都能从这个公式起步。

业务对象 + 数量口径 + 备注上下文 + 完成状态 = 可落地的移动工作台

13.2 复用时要注意什么

复用时不能只替换标题，还要同步调整默认数据、统计文案、功能标签和业务备注，否则页面会失去行业可信度。

总结

Stall Payment Ledger 通过简洁的 ArkTS 代码，把摊位收款台账中的高频记录动作整理成移动端工作台。它的核心价值在于让记录可新增、数量可统计、备注可追溯、状态可闭环。

对 夜市摊主、快闪店店员、市集运营者 来说，这种应用能够降低现场沟通成本，并把当天任务形成清晰列表。随着持久化、提醒和行业字段补齐，它可以继续扩展成更完整的业务工具。

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

相关资源：

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