鸿蒙 ArkTS 实战：Scan Inventory Entry 从系统能力到状态管理完整解析

鸿蒙 ArkTS 实战：Scan Inventory Entry 从系统能力到状态管理完整解析

前言

Scan Inventory Entry 是一个面向扫码库存录入的鸿蒙 ArkTS 单页工具。它用列表、统计卡片、权限提示开关和状态切换，把一个具体系统能力场景整理成可操作的移动端工作台。

项目服务于 通过条码或 SKU 记录库存数量、更新状态和历史检索备注。对仓库管理员、门店店员、盘点负责人来说，核心价值是把分散的现场信息收束为可记录、可统计、可切换状态的条目。

业务痛点：库存录入如果缺少扫码、历史查询和状态确认，容易造成重复录入或数量误差。

图示说明：本文围绕 Scan Inventory Entry 的数据模型、统计卡片、权限提示和列表状态切换进行拆解。

一、业务定位与产品目标

1.1 使用场景

把 SKU、库存数量、更新备注和激活状态放在列表中，适合移动盘点场景快速核对。 当前项目虽然没有直接调用真实硬件 API，但页面结构已经把业务记录、权限提示和状态反馈组织清楚，适合作为系统能力类应用的前端雏形。

1.2 页面能力概览

当前页面可以拆成四个区域：

1. 顶部标题，明确工具的系统能力场景。

2. 统计卡片，展示Stock与Active。

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 负责应用入口。系统能力类工具后续接入权限和硬件 API 时，仍然需要从这个入口模型开始组织。

{"module":{"name":"entry","type":"entry","abilities":[{"name":"EntryAbility","srcEntry":"./ets/entryability/EntryAbility.ets","exported":true}]},"topic":"扫码库存录入"}

三、数据模型：条目记录的最小闭环

3.1 字段设计

SystemItem使用title、amount、note、active四个字段描述一条记录。它把对象名称、数量口径、备注上下文和状态开关收束在同一个模型中。

interfaceSystemItem{title:string;amount:number;note:string;active:boolean;}@Stateitems:SystemItem[]=[{title:'SKU 88021',amount:24,note:'Stock updated',active:false},{title:'SKU 99018',amount:12,note:'History searchable',active:false}];

3.2 默认数据分析

默认数据不是空白占位，而是直接体现项目的核心使用场景。

这两条记录分别触达条码扫描、商品录入、库存更新和历史搜索，让页面首次打开时就能表达业务语义。

四、状态管理：输入与权限提示

4.1 页面状态字段

页面使用@State管理输入框、permissionOn开关和状态文案。开关在界面中显示为Permission note，用于表达权限或辅助提示。

@StatetitleText:string='';@StateamountText:string='';@StatenoteText:string='';@StatepermissionOn:boolean=true;@Statestatus:string='System capability demo ready';

4.2 输入与正式记录分离

标题、数量和备注先保存在输入状态中，只有点击按钮并通过校验后才会写入列表。

关键点：系统能力类工具更需要明确的权限提示和状态反馈，否则用户很难理解当前记录是否已经进入可用状态。

五、统计逻辑：总量与状态数

5.1 总量统计

totalAmount()遍历 items，把每条记录的 amount 相加，形成顶部Stock指标。

5.2 状态统计

activeCountValue()统计active为 true 的条目数量，并以状态数/总数的形式展示。

privatetotalAmount():number{lettotal=0;this.items.forEach((item:SystemItem)=>{total+=item.amount;});returntotal;}privateactiveCountValue():number{letcount=0;this.items.forEach((item:SystemItem)=>{if(item.active){count++;}});returncount;}

六、新增记录流程

6.1 校验规则

新增时先把数量转换为数字，再校验标题是否为空、数量是否有效。无效输入不会写入列表。

6.2 顶部插入策略

新记录会插入到列表顶部，并清空输入框。这样最新记录总在最容易看到的位置。

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

七、状态切换与刷新机制

7.1 切换逻辑

勾选列表项时，toggleActive()会反转active字段，并通过数组展开触发界面刷新。

privatetoggleActive(index:number):void{this.items[index].active=!this.items[index].active;this.items=[...this.items];}

7.2 视觉反馈

状态开启后的记录使用浅绿色背景，未开启记录保持白色。颜色反馈能让用户快速扫出当前状态。

八、统计卡片与能力标签

8.1 顶部统计卡片

顶部双卡片分别展示业务总量和状态数量。颜色区分能降低移动端扫描成本。

Row({space:10}){Column({space:4}){Text('Stock').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('Active').fontSize(13).fontColor('#475569')Text(this.activeCountValue()+'/'+this.items.length).fontSize(24).fontWeight(FontWeight.Bold).fontColor('#047857')}.layoutWeight(1).padding(14).backgroundColor('#D1FAE5').borderRadius(8)}

8.2 功能标签解读

四个标签分别是Barcode scan、Item entry、Stock update、History search，它们概括了当前工具的关键能力。

• 条码扫描：确认记录对象。

• 商品录入：表达系统能力或使用位置。

• 库存更新：补充提醒、参数或管理能力。

• 历史搜索：形成可复用的操作依据。

九、表单与列表渲染

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.addItem())}

9.2 列表区域

列表使用ForEach渲染，每行包含状态勾选、标题、备注和数量。

ForEach(this.items,(item:SystemItem,index:number)=>{Row(){Toggle({type:ToggleType.Checkbox,isOn:item.active}).onChange(()=>this.toggleActive(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.active?'#DCFCE7':'#FFFFFF').borderRadius(8).width('100%')})

十、业务流程复盘

10.1 标准路径

Scan Inventory Entry 的一次完整使用可以拆成四步：

1. 录入或扫描 SKU。
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、时间戳、来源和权限状态，便于后续同步和检索。

interfacePersistedSystemItem{id:string;title:string;amount:number;note:string;active:boolean;updatedAt:number;}

11.2 系统能力扩展

后续可以接入扫码组件、库存接口、批次管理和历史搜索。

扩展顺序建议为：

1. 增加本地持久化，保证记录不丢失。

2. 接入对应系统能力或硬件 API。

3. 增加权限说明、历史搜索和导出能力。

十二、调试与验证

12.1 核心验证点

验证时重点检查新增、统计、状态切换、背景变化和错误提示。

12.2 运行检查

可以在 DevEco Studio 中运行预览或真机，按输入、状态切换、复盘路径逐项验证。

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

十三、可复用的系统工具模式

13.1 通用公式

这类工具可以抽象为一个通用公式：对象名称、数量口径、上下文备注、状态开关。

对象名称 + 数量口径 + 上下文备注 + 状态开关 = 可复用的系统能力工作台

13.2 复用边界

复用时不能只改标题，还要同步调整默认数据、统计文案、能力标签和业务说明，否则页面会失去真实场景感。

总结

Scan Inventory Entry 用简洁的 ArkTS 单页结构实现了扫码库存录入的记录、统计、权限提示和状态切换闭环。它为后续接入真实系统能力提供了清晰的页面基础。

对 仓库管理员、门店店员、盘点负责人 来说，这种工具能降低现场记录和状态确认成本。补齐持久化、权限和系统 API 后，可以继续演进成更完整的业务工具。

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

相关资源：

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