鸿蒙 ArkTS 实战Sensor Compass 从系统能力到状态管理完整解析前言Sensor Compass 是一个面向传感器指南针的鸿蒙 ArkTS 单页工具。它用列表、统计卡片、权限提示开关和状态切换把一个具体系统能力场景整理成可操作的移动端工作台。项目服务于 记录指南针方向、水平校准、户外模式和传感器使用提示。对户外用户、摄影辅助用户、传感器开发者来说核心价值是把分散的现场信息收束为可记录、可统计、可切换状态的条目。业务痛点方向和水平校准依赖传感器状态如果没有校准提示和场景备注实际使用时容易误判。图示说明本文围绕 Sensor Compass 的数据模型、统计卡片、权限提示和列表状态切换进行拆解。一、业务定位与产品目标1.1 使用场景项目把方向读数、校准备注和激活状态放到一屏便于快速记录和验证传感器场景。 当前项目虽然没有直接调用真实硬件 API但页面结构已经把业务记录、权限提示和状态反馈组织清楚适合作为系统能力类应用的前端雏形。1.2 页面能力概览当前页面可以拆成四个区域顶部标题明确工具的系统能力场景。统计卡片展示Heading与Active。功能标签提示具体能力边界。表单与列表完成新增、备注展示和状态切换。页面区域代码元素业务作用标题区Text标识传感器指南针统计区totalAmount / activeCountValue统计方向读数和激活进度标签区四个能力标签明确功能范围列表区ForEach展示条目并切换状态二、工程结构与入口文件2.1 目录结构项目采用标准 Stage 工程核心页面位于entry/src/main/ets/pages/Index.ets。对单页工具来说这种结构便于快速定位业务逻辑。entry/ src/ main/ ets/ entryability/ EntryAbility.ets pages/ Index.ets module.json52.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:North check,amount:12,note:Calibrate by figure eight,active:false},{title:Tripod level,amount:1,note:Outdoor mode enabled,active:false}];3.2 默认数据分析默认数据不是空白占位而是直接体现项目的核心使用场景。默认标题数量备注ActiveNorth check12Calibrate by figure eightfalseTripod level1Outdoor mode enabledfalse这两条记录分别触达方向视图、水平工具、校准提示和户外模式让页面首次打开时就能表达业务语义。四、状态管理输入与权限提示4.1 页面状态字段页面使用State管理输入框、permissionOn开关和状态文案。开关在界面中显示为Permission note用于表达权限或辅助提示。StatetitleText:string;StateamountText:string;StatenoteText:string;StatepermissionOn:booleantrue;Statestatus:stringSystem capability demo ready;4.2 输入与正式记录分离标题、数量和备注先保存在输入状态中只有点击按钮并通过校验后才会写入列表。关键点系统能力类工具更需要明确的权限提示和状态反馈否则用户很难理解当前记录是否已经进入可用状态。五、统计逻辑总量与状态数5.1 总量统计totalAmount()遍历 items把每条记录的 amount 相加形成顶部Heading指标。5.2 状态统计activeCountValue()统计active为 true 的条目数量并以状态数/总数的形式展示。privatetotalAmount():number{lettotal0;this.items.forEach((item:SystemItem){totalitem.amount;});returntotal;}privateactiveCountValue():number{letcount0;this.items.forEach((item:SystemItem){if(item.active){count;}});returncount;}函数统计来源页面位置业务意义totalAmountamountHeading掌握方向读数规模activeCountValueactiveActive掌握激活状态toggleActiveindex列表勾选更新单条记录状态六、新增记录流程6.1 校验规则新增时先把数量转换为数字再校验标题是否为空、数量是否有效。无效输入不会写入列表。6.2 顶部插入策略新记录会插入到列表顶部并清空输入框。这样最新记录总在最容易看到的位置。privateaddItem():void{constamountNumber(this.amountText);if(this.titleText.trim().length0||!Number.isFinite(amount)){this.statusEnter title and valid number;return;}this.items[{title:this.titleText,amount:Math.round(amount),note:this.noteText.length0?this.noteText:No note yet,active:false},...this.items];this.titleText;this.amountText;this.noteText;this.statusRecord added;}七、状态切换与刷新机制7.1 切换逻辑勾选列表项时toggleActive()会反转active字段并通过数组展开触发界面刷新。privatetoggleActive(index:number):void{this.items[index].active!this.items[index].active;this.items[...this.items];}7.2 视觉反馈状态开启后的记录使用浅绿色背景未开启记录保持白色。颜色反馈能让用户快速扫出当前状态。状态背景色用户感知未开启#FFFFFF仍需处理或确认已开启#DCFCE7已进入激活状态输入异常状态文案需要修正标题或数量八、统计卡片与能力标签8.1 顶部统计卡片顶部双卡片分别展示业务总量和状态数量。颜色区分能降低移动端扫描成本。Row({space:10}){Column({space:4}){Text(Heading).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 功能标签解读四个标签分别是Direction view、Level tool、Calibrate tip、Outdoor mode它们概括了当前工具的关键能力。方向视图确认记录对象。水平工具表达系统能力或使用位置。校准提示补充提醒、参数或管理能力。户外模式形成可复用的操作依据。九、表单与列表渲染9.1 表单区域表单由标题、数量和备注三个输入框组成配合按钮完成记录创建。Column({space:10}){TextInput({placeholder:Title,text:this.titleText}).onChange((value:string)this.titleTextvalue)TextInput({placeholder:Number,text:this.amountText}).type(InputType.Number).onChange((value:string)this.amountTextvalue)TextInput({placeholder:Note,text:this.noteText}).onChange((value:string)this.noteTextvalue)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 标准路径Sensor Compass 的一次完整使用可以拆成四步录入方向任务。填写方向读数。备注校准方式。切换活跃状态。10.2 异常路径当标题为空或数量非法时新增动作会被拦截避免无效记录进入列表。constamountNumber(this.amountText);constinvalidthis.titleText.trim().length0||!Number.isFinite(amount);if(invalid){this.statusEnter title and valid number;}十一、扩展设计11.1 持久化模型正式应用可以给记录增加 id、时间戳、来源和权限状态便于后续同步和检索。interfacePersistedSystemItem{id:string;title:string;amount:number;note:string;active:boolean;updatedAt:number;}11.2 系统能力扩展后续可以接入方向传感器、水平仪动画、校准引导和户外模式配置。扩展顺序建议为增加本地持久化保证记录不丢失。接入对应系统能力或硬件 API。增加权限说明、历史搜索和导出能力。十二、调试与验证12.1 核心验证点验证时重点检查新增、统计、状态切换、背景变化和错误提示。12.2 运行检查可以在 DevEco Studio 中运行预览或真机按输入、状态切换、复盘路径逐项验证。# 常规验证动作# 1. 输入标题、数量和备注# 2. 点击 Add record 或 Add item# 3. 检查新记录是否位于顶部# 4. 勾选记录并观察统计变化验证项预期结果业务意义有效新增列表顶部出现新记录快速沉淀现场信息空标题显示错误状态避免无效记录勾选状态统计和背景同步变化明确当前状态空备注写入 No note yet保持列表可读十三、可复用的系统工具模式13.1 通用公式这类工具可以抽象为一个通用公式对象名称、数量口径、上下文备注、状态开关。对象名称 数量口径 上下文备注 状态开关 可复用的系统能力工作台13.2 复用边界复用时不能只改标题还要同步调整默认数据、统计文案、能力标签和业务说明否则页面会失去真实场景感。总结Sensor Compass 用简洁的 ArkTS 单页结构实现了传感器指南针的记录、统计、权限提示和状态切换闭环。它为后续接入真实系统能力提供了清晰的页面基础。对 户外用户、摄影辅助用户、传感器开发者 来说这种工具能降低现场记录和状态确认成本。补齐持久化、权限和系统 API 后可以继续演进成更完整的业务工具。如果这篇文章对你有帮助可以点赞、收藏并关注后续会继续拆解更多鸿蒙 ArkTS 实战项目。相关资源HarmonyOS 应用开发ArkTS 语言基础ArkUI 声明式开发DevEco StudioStage 模型应用结构Ability Kit