鸿蒙 ArkTS 实战Number Slide Puzzle 从数字滑块拼图到记录管理完整解析前言Number Slide Puzzle 是一个面向数字滑块拼图场景的鸿蒙 ArkTS 单页应用。它不是只展示静态文案而是围绕记录数据、分数统计、开关配置、表单录入和列表交互构建了完整的轻量业务闭环。这篇文章会直接从项目里的Index.ets入手拆解它如何通过State管理页面状态如何用ForEach渲染记录列表如何用Toggle完成开关与勾选交互以及如何把新增记录插入到列表头部。这类小应用的价值在于结构清晰数据模型简单、交互路径短、状态变化可追踪适合用来练习鸿蒙 ArkTS 的声明式 UI 与状态驱动思维。上图可作为文章发布时的界面结构配图表达“顶部指标、功能标签、配置开关、录入表单、记录列表”的信息层次。实际发布时如果已有运行截图也可以替换为项目真机截图。一、项目定位与功能目标1.1 应用场景用关卡、步数、难度与撤销重开信息记录数字滑块拼图表现适合从静态成绩页扩展到完整拼图玩法。从代码看页面已经具备一个可运行工具的基本骨架顶部显示累计步数中部提供功能标签和声音或辅助开关下方通过输入框新增记录并用复选框标记活跃记录。1.2 功能边界当前版本聚焦单页体验不引入路由、不依赖后端、不使用复杂状态库。这样的边界很适合做 MVP先完成记录展示和新增。再验证核心指标是否符合玩法。最后再接入真正的游戏逻辑、持久化或资源系统。模块当前能力对应源码数据模型定义标题、分值、备注、选中态GameRecord统计卡片汇总Moves与选中数量totalScore/totalAmount、selectedCount表单录入输入名称、数值、备注TextInput列表交互勾选记录并更新背景ForEach、Toggle二、目录入口与页面职责2.1 主页面文件核心逻辑集中在entry/src/main/ets/pages/Index.ets。页面使用Entry与Component声明入口组件通过build()返回 UI 树。EntryComponentstruct Index{build(){Scroll(){Column({space:14}){Text(Number Slide Puzzle)}}}}2.2 单页结构这个页面的职责可以拆成五层标题层展示Number Slide Puzzle。统计层展示Moves与 Selected。标签层展示Tile puzzle, Move stats, Difficulty level, Undo restart。录入层新增一条业务记录。列表层渲染记录并支持勾选。这种结构对小型鸿蒙应用很实用因为每个区域都对应一段明确的状态读写逻辑。三、数据模型设计3.1 记录接口项目使用GameRecord描述列表项每条记录都包含标题、数值、备注和活跃状态。interfaceGameRecord{title:string;score:number;note:string;active:boolean;}这里的active字段非常关键。它不是临时 UI 状态而是记录级状态决定这一条数据是否被选中也决定列表项背景是否变为绿色。3.2 字段语义字段类型业务含义titlestring轮次、关卡或队伍名称scorenumber步数用于累计统计notestring记录补充信息activeboolean是否被选中在数字滑块拼图场景里score承载的是步数。例如默认数据中已经包含3x3 level与4x4 level两条记录说明页面并不是空壳而是围绕真实玩法指标组织数据。四、默认数据与业务含义4.1 初始记录项目启动时会直接展示两条默认记录方便用户进入页面后立即理解用途。Staterecords:GameRecord[][{title:3x3 level,score:42,note:Undo used 2,active:false},{title:4x4 level,score:88,note:Restart available,active:false}];名称数值备注初始状态3x3 level42Undo used 2false4x4 level88Restart availablefalse4.2 为什么保留默认数据默认数据有三个作用避免首次打开页面时列表为空。给用户展示记录格式。为统计卡片提供初始值。对数字滑块拼图这类轻量工具来说默认样例比空页面更容易让用户理解“该填什么、填完后会发生什么”。五、状态管理拆解5.1 页面状态页面使用多个State字段保存输入内容、开关状态、记录集合和状态提示。StatetitleText:string;StatescoreText:string;StatenoteText:string;StatesoundOn:booleantrue;Statestatus:stringGame session ready;这些状态都直接参与 UI 渲染。输入框变化会更新titleText、scoreText、noteText按钮点击会读取这些字段新增成功后又会清空它们。5.2 状态更新路径状态触发位置页面反馈records新增记录、切换勾选列表重新渲染titleText名称输入框表单内容同步scoreText数值输入框用于数值校验noteText备注输入框写入记录备注soundOnSound开关保存配置状态status表单提交展示成功或错误提示六、统计逻辑实现6.1 汇总Moves页面通过遍历记录集合计算累计步数。privatetotalScore():number{lettotal0;this.records.forEach((item:GameRecord){totalitem.score;});returntotal;}这个函数没有缓存也没有引入额外状态。只要records发生变化声明式 UI 会重新读取计算结果顶部统计卡片随之更新。6.2 统计选中数量选中数量通过active字段计算。privateselectedCount():number{letcount0;this.records.forEach((item:GameRecord){if(item.active){count;}});returncount;}selectedCount()的返回值会以已选数量/总数量形式展示。这个设计对数字滑块拼图很实用用户既能看到总体记录规模也能看到当前被重点标记的记录数量。七、顶部指标卡片7.1 视觉层次顶部使用两个并排卡片展示核心指标左侧是Moves右侧是 Selected。Row({space:10}){Column({space:4}){Text(Moves).fontSize(13).fontColor(#475569)Text(String(this.totalScore())).fontSize(24).fontWeight(FontWeight.Bold)}.layoutWeight(1).padding(14).backgroundColor(#FEE2E2).borderRadius(8)Column({space:4}){Text(Selected).fontSize(13).fontColor(#475569)Text(this.selectedCount()/this.records.length).fontSize(24).fontWeight(FontWeight.Bold)}.layoutWeight(1).padding(14).backgroundColor(#DBEAFE).borderRadius(8)}左侧指标强调业务成果右侧指标强调列表选择状态。两者放在同一行可以让用户在进入页面后第一眼看到结果。7.2 指标设计指标来源作用Moves所有记录的score汇总衡量整体成绩Selectedactive为 true 的记录数标记当前关注记录总记录数records.length展示列表规模对于Number Slide Puzzle来说Moves不是装饰信息而是当前玩法最重要的结果指标。八、功能标签区域8.1 标签代码页面通过两行标签表达应用能力。Column({space:8}){Row({space:8}){Text(Tile puzzle).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)Text(Move stats).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)}Row({space:8}){Text(Difficulty level).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)Text(Undo restart).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)}}8.2 标签对应能力序号标签含义1Tile puzzle主玩法入口2Move stats过程控制能力3Difficulty level辅助信息呈现4Undo restart结果沉淀能力这些标签让用户在无需阅读说明的情况下理解应用方向。比如Tile puzzle指向主玩法Move stats指向过程控制Difficulty level与Undo restart则补充辅助能力和结果沉淀。九、开关交互设计9.1 开关状态页面提供Sound开关状态保存在soundOn中。Row(){Text(Sound).fontSize(16).fontColor(#374151)Blank()Toggle({type:ToggleType.Switch,isOn:this.soundOn}).onChange((checked:boolean)this.soundOnchecked)}9.2 交互意义在当前版本里开关主要承担配置入口职责。对数字滑块拼图来说它可以继续映射到声音、提示、辅助模式或教学引导。这种做法的优点是扩展成本低后续只需要在业务逻辑里读取soundOn就可以决定是否播放音效、显示提示或启用辅助规则。十、表单录入流程10.1 输入区代码录入区包含名称、数值、备注三个输入框以及一个提交按钮。Column({space:10}){TextInput({placeholder:Round name,text:this.titleText}).onChange((value:string)this.titleTextvalue)TextInput({placeholder:Score,text:this.scoreText}).type(InputType.Number).onChange((value:string)this.scoreTextvalue)TextInput({placeholder:Note,text:this.noteText}).onChange((value:string)this.noteTextvalue)Button(Add score).height(42).width(100%).onClick(()this.addRecord())}10.2 表单规则表单提交前会校验两个条件名称不能为空。数值必须能转换为有效数字。如果校验失败状态提示会变成Enter round and valid score如果成功会创建新记录并显示Score saved。10.3 用户体验细节数值输入框使用InputType.Number可以降低输入非法字符的概率。备注允许为空但保存时会补成No note yet避免列表出现空白说明。十一、新增记录逻辑11.1 新增方法新增方法是页面最核心的写操作。privateaddRecord():void{constscoreNumber(this.scoreText);if(this.titleText.trim().length0||!Number.isFinite(score)){this.statusEnter round and valid score;return;}this.records[{title:this.titleText,score:Math.round(score),note:this.noteText.length0?this.noteText:No note yet,active:false},...this.records];this.titleText;this.scoreText;this.noteText;this.statusScore saved;}11.2 插入到列表头部新记录使用[newItem, ...oldItems]的方式放到列表最前面。这样用户提交后可以立即在第一屏看到刚添加的记录不需要滚动到底部。11.3 数值处理项目使用Math.round()保存整数。对步数这类指标来说整数更利于展示和比较也能避免小数影响顶部统计读数。十二、列表渲染与勾选更新12.1 列表代码记录列表通过ForEach渲染每条记录都带有复选框。ForEach(this.records,(item:GameRecord,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)Text(item.note).fontSize(14).fontColor(#475569)}.layoutWeight(1).margin({left:8})Text(String(item.score)).fontSize(18).fontWeight(FontWeight.Bold)}.padding(14).backgroundColor(item.active?#DCFCE7:#FFFFFF).borderRadius(8)})12.2 切换状态勾选状态通过toggleActive(index)更新。privatetoggleActive(index:number):void{this.records[index].active!this.records[index].active;this.records[...this.records];}这里有一个重要细节修改数组元素后代码又执行了this.records [...this.records]。这会生成新的数组引用确保页面感知到状态变化并刷新列表。12.3 选中态反馈列表项背景使用条件表达式backgroundColor(item.active?#DCFCE7:#FFFFFF)绿色背景让活跃记录非常明显适合用来标记当前重点轮次、最好成绩或正在复盘的记录。十三、界面布局与配色13.1 布局结构页面外层使用Scroll内部使用Column按垂直方向排列。这样即使记录增多用户也可以继续向下浏览。Scroll(){Column({space:14}){Text(Number Slide Puzzle)// stats// tags// switch// form// list}.padding(18).width(100%)}.height(100%).backgroundColor(#F8FAFC)13.2 配色策略区域颜色作用页面背景#F8FAFC保持轻量、干净统计红色#DC2626强调主要数值统计蓝色#1D4ED8强调选择状态选中绿色#DCFCE7表达已激活表单灰底#F1F5F9与列表内容区分这种配色不会喧宾夺主适合成绩记录、训练工具和轻量小游戏后台页。十四、运行验证路径14.1 表单验证可以按以下路径验证页面行为打开页面确认默认显示两条记录。直接点击Add score观察status是否显示Enter round and valid score。输入Daily round与99点击Add score。确认新记录出现在列表顶部。勾选第一条记录确认背景变绿且 Selected 数量增加。// 手工验证路径this.titleTextDaily round;this.scoreText99;this.noteTextManual input;this.addRecord();// 预期状态// status: Score saved// first item: Daily round / 99 / Manual input14.2 关键断言验证点预期结果空标题提交显示Enter round and valid score合法数值提交显示Score saved新增记录插入列表第一位勾选记录active取反Selected 更新顶部统计Moves随列表变化更新14.3 真实玩法扩展可以继续接入可解性校验、滑块移动、撤销栈、重开按钮和最少步数统计。 扩展时仍然可以复用当前记录结构只需要把真正的游戏结果写入score再调用相同的新增逻辑。十五、工程复盘与总结15.1 本项目的实现重点当前页面把步数作为指标强调不同棋盘难度下的完成成本便于比较 3x3 与 4x4 关卡。从工程角度看它体现了鸿蒙 ArkTS 小型应用的几个关键点用接口固定列表数据形态。用State驱动页面刷新。用函数封装统计、提交和切换逻辑。用ForEach保持列表渲染清晰。用状态提示给用户即时反馈。15.2 可复用经验这套结构可以迁移到很多单页工具学习打卡、训练记录、闯关成绩、家庭游戏计分、轻量任务追踪等。只要业务对象可以抽象成“名称、数值、备注、状态”就可以复用当前实现方式。总结Number Slide Puzzle用非常直接的 ArkTS 代码完成了数字滑块拼图的记录管理闭环。它的核心不在复杂算法而在清晰的数据流输入内容进入State提交时生成记录记录变化触发统计更新勾选状态再反向影响列表样式和 Selected 数量。对于学习鸿蒙应用开发的人来说这个项目适合用来理解声明式 UI、状态刷新、表单校验和列表渲染。对于实际产品原型来说它也已经具备继续扩展为完整玩法页面的基础。相关资源HarmonyOS 开发者官网ArkTS 语言基础ArkUI 组件开发状态管理说明TextInput 组件Toggle 组件ForEach 渲染控制DevEco Studio
