鸿蒙 ArkTS 实战：Family Word Guess Cards 从家庭猜词卡片到记录管理完整解析 鸿蒙 ArkTS 实战Family Word Guess Cards 从家庭猜词卡片到记录管理完整解析前言Family Word Guess Cards 是一个面向家庭猜词卡片场景的鸿蒙 ArkTS 单页应用。它不是只展示静态文案而是围绕记录数据、分数统计、开关配置、表单录入和列表交互构建了完整的轻量业务闭环。这篇文章会直接从项目里的Index.ets入手拆解它如何通过State管理页面状态如何用ForEach渲染记录列表如何用Toggle完成开关与勾选交互以及如何把新增记录插入到列表头部。这类小应用的价值在于结构清晰数据模型简单、交互路径短、状态变化可追踪适合用来练习鸿蒙 ArkTS 的声明式 UI 与状态驱动思维。上图可作为文章发布时的界面结构配图表达“顶部指标、功能标签、配置开关、录入表单、记录列表”的信息层次。实际发布时如果已有运行截图也可以替换为项目真机截图。一、项目定位与功能目标1.1 应用场景面向家庭聚会或课堂分组猜词用词库、队伍得分、倒计时和跳过记录管理每轮结果。从代码看页面已经具备一个可运行工具的基本骨架顶部显示累计队伍分数中部提供功能标签和声音或辅助开关下方通过输入框新增记录并用复选框标记活跃记录。1.2 功能边界当前版本聚焦单页体验不引入路由、不依赖后端、不使用复杂状态库。这样的边界很适合做 MVP先完成记录展示和新增。再验证核心指标是否符合玩法。最后再接入真正的游戏逻辑、持久化或资源系统。模块当前能力对应源码数据模型定义标题、分值、备注、选中态GameRecord统计卡片汇总Team score与选中数量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(Family Word Guess Cards)}}}}2.2 单页结构这个页面的职责可以拆成五层标题层展示Family Word Guess Cards。统计层展示Team score与 Selected。标签层展示Word bank, Team score, Countdown, Skip log。录入层新增一条业务记录。列表层渲染记录并支持勾选。这种结构对小型鸿蒙应用很实用因为每个区域都对应一段明确的状态读写逻辑。三、数据模型设计3.1 记录接口项目使用GameRecord描述列表项每条记录都包含标题、数值、备注和活跃状态。interfaceGameRecord{title:string;score:number;note:string;active:boolean;}这里的active字段非常关键。它不是临时 UI 状态而是记录级状态决定这一条数据是否被选中也决定列表项背景是否变为绿色。3.2 字段语义字段类型业务含义titlestring轮次、关卡或队伍名称scorenumber队伍分数用于累计统计notestring记录补充信息activeboolean是否被选中在家庭猜词卡片场景里score承载的是队伍分数。例如默认数据中已经包含Team Red与Team Blue两条记录说明页面并不是空壳而是围绕真实玩法指标组织数据。四、默认数据与业务含义4.1 初始记录项目启动时会直接展示两条默认记录方便用户进入页面后立即理解用途。Staterecords:GameRecord[][{title:Team Red,score:18,note:Skipped 2,active:false},{title:Team Blue,score:16,note:Countdown 60s,active:false}];名称数值备注初始状态Team Red18Skipped 2falseTeam Blue16Countdown 60sfalse4.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 汇总Team score页面通过遍历记录集合计算累计队伍分数。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 视觉层次顶部使用两个并排卡片展示核心指标左侧是Team score右侧是 Selected。Row({space:10}){Column({space:4}){Text(Team score).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 指标设计指标来源作用Team score所有记录的score汇总衡量整体成绩Selectedactive为 true 的记录数标记当前关注记录总记录数records.length展示列表规模对于Family Word Guess Cards来说Team score不是装饰信息而是当前玩法最重要的结果指标。八、功能标签区域8.1 标签代码页面通过两行标签表达应用能力。Column({space:8}){Row({space:8}){Text(Word bank).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)Text(Team score).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)}Row({space:8}){Text(Countdown).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)Text(Skip log).layoutWeight(1).fontSize(13).textAlign(TextAlign.Center)}}8.2 标签对应能力序号标签含义1Word bank主玩法入口2Team score过程控制能力3Countdown辅助信息呈现4Skip log结果沉淀能力这些标签让用户在无需阅读说明的情况下理解应用方向。比如Word bank指向主玩法Team score指向过程控制Countdown与Skip log则补充辅助能力和结果沉淀。九、开关交互设计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(Family Word Guess Cards)// 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 更新顶部统计Team score随列表变化更新14.3 真实玩法扩展可以扩展卡片抽词、禁词提示、队伍轮换、倒计时音效和跳过次数限制。 扩展时仍然可以复用当前记录结构只需要把真正的游戏结果写入score再调用相同的新增逻辑。十五、工程复盘与总结15.1 本项目的实现重点当前页面把队伍成绩和跳过情况放在同一个记录模型里方便快速比较红队与蓝队表现。从工程角度看它体现了鸿蒙 ArkTS 小型应用的几个关键点用接口固定列表数据形态。用State驱动页面刷新。用函数封装统计、提交和切换逻辑。用ForEach保持列表渲染清晰。用状态提示给用户即时反馈。15.2 可复用经验这套结构可以迁移到很多单页工具学习打卡、训练记录、闯关成绩、家庭游戏计分、轻量任务追踪等。只要业务对象可以抽象成“名称、数值、备注、状态”就可以复用当前实现方式。总结Family Word Guess Cards用非常直接的 ArkTS 代码完成了家庭猜词卡片的记录管理闭环。它的核心不在复杂算法而在清晰的数据流输入内容进入State提交时生成记录记录变化触发统计更新勾选状态再反向影响列表样式和 Selected 数量。对于学习鸿蒙应用开发的人来说这个项目适合用来理解声明式 UI、状态刷新、表单校验和列表渲染。对于实际产品原型来说它也已经具备继续扩展为完整玩法页面的基础。相关资源HarmonyOS 开发者官网ArkTS 语言基础ArkUI 组件开发状态管理说明TextInput 组件