鸿蒙 ArkTS 实战Murder Mystery Party 从剧本推理聚会到兴趣社群工具完整解析前言Murder Mystery Party 是一个围绕线下剧本活动设计的鸿蒙 ArkTS 单页应用。它把 维护剧本投票、角色分配、场地时间、总费用和人均分摊 这类真实活动需求拆成状态字段、输入组件、按钮动作和结果反馈。本文基于项目真实的Index.ets源码展开重点分析它如何用State管理数据如何用 ArkUI 组件组织页面以及如何把一次兴趣活动变成可记录、可更新、可扩展的移动端工具。图示说明配图用于表达鸿蒙应用中状态、组件和交互反馈的关系帮助理解本文的页面拆解思路。可以结合 HarmonyOS 应用开发文档、ArkTS 语言基础、ArkUI 声明式开发范式、组件参考 等资料阅读本文。兴趣社群类工具的关键不是功能越多越好而是一次记录能否在当前页面里形成清楚的闭环。一、项目定位与用户场景1.1 业务场景剧本推理聚会 聚焦的场景是维护剧本投票、角色分配、场地时间、总费用和人均分摊。这类场景通常发生在线下活动前后用户需要快速打开页面确认信息修改内容然后保存一条明确反馈。1.2 目标读者这篇文章适合想学习鸿蒙 ArkTS 小应用开发的读者尤其适合关注兴趣社群工具、活动记录页面和状态驱动 UI的开发者。1.3 页面价值页面不追求复杂流程而是让用户在一个屏幕内完成主要动作。查看当前活动核心信息。修改关键字段。点击按钮触发状态变化。从结果文字或数字中确认变化。二、工程结构与入口组件2.1 页面位置项目核心代码位于入口页面。entry/ src/ main/ ets/ pages/ Index.ets这种结构让文章分析可以直接围绕页面源码展开。2.2 组件声明EntryComponentstruct Index{build(){// 声明式 UI}}Entry表示页面入口Component表示这是一个可渲染组件。2.3 单页工具边界当前项目没有引入多页面路由或远程接口所有交互都围绕当前页面状态完成。这让它非常适合作为 ArkTS 实战学习案例。三、状态模型设计3.1 状态字段总览状态字段初始值页面职责scriptNameNight Train剧本名称roleDetective: Chen角色分配placeTimeRoom B, 19:00场地时间cost360总费用players6玩家人数这些字段共同构成了 剧本推理聚会 的业务模型。3.2 状态命名的直观性字段名都直接指向页面语义。例如scriptName是主记录字段players是结果或计数字段。这种命名让源码可读性很高。3.3 核心状态与函数源码StatescriptName:stringNight Train;Staterole:stringDetective: Chen;StateplaceTime:stringRoom B, 19:00;Statecost:string360;Stateplayers:number6;assign():void{this.roleRole assigned for player this.players;}这段代码展示了项目最重要的状态和交互函数。状态变化后页面中引用这些状态的组件会随之刷新。四、交互逻辑拆解4.1 交互表交互点源码行为用户看到的结果assign根据 players 生成角色分配文案当前页面即时刷新Joinplayers 自增当前页面即时刷新Split 计算根据 cost 和 players 展示人均费用当前页面即时刷新每个交互都对应一个明确的业务动作。4.2 输入同步项目通过TextInput的onChange回调同步输入。TextInput({text:this.scriptName,placeholder:剧本名称}).onChange((v:string)this.scriptNamev)这种写法直接、轻量适合字段数量不多的活动页面。4.3 按钮动作按钮通常只做一件事修改状态。Button(Save).width(100%).onClick((){this.playersthis.scriptName;})动作越短用户越容易理解。五、布局结构分析5.1 页面布局概览左侧深紫统计栏展示玩家数右侧表单维护剧本、角色、场地时间和费用分摊。这个布局把主信息放在更显眼的位置把编辑区放在下方或右侧。5.2 关键 UI 片段Column({space:12}){Text(Mystery Party).fontSize(24).fontWeight(FontWeight.Bold)Text(this.players.toString()).fontSize(56).fontWeight(FontWeight.Bold).fontColor(#FFFFFF)Text(players).fontColor(#E0E7FF)}.width(34%).height(100%).justifyContent(FlexAlign.Center).backgroundColor(#312E81)这段 UI 代码体现了项目的主要视觉结构。5.3 滚动容器的作用活动记录类页面经常包含多个输入框。Scroll(){Column({space:16}){// 活动内容}.padding(20).width(100%)}滚动容器可以保证小屏设备上也能完整操作。六、视觉层级与主题色6.1 当前配色当前页面背景色是#FFFFFF强调色是#312E81。颜色被用来区分主信息和辅助信息而不是单纯装饰。6.2 字号层级层级常见字号用途主标题30 左右页面主题强指标54 到 56数量、评分、进度内容文本15 到 24输入结果和说明6.3 卡片留白项目中大量使用padding和borderRadius。Text(Info).padding(16).backgroundColor(#312E81).borderRadius(8)这能让活动信息更容易扫读。七、数据计算与边界7.1 数字自增项目中有照片数、录音数、点评数、观察次数、保存次数、进度、订单、评分、玩家数和投票数等数字状态。this.count;自增逻辑要保持结果可见否则用户无法确认动作是否生效。7.2 上限控制当字段有自然上限时应使用Math.min。this.progressMath.min(100,this.progress10);this.ratingMath.min(100,this.rating1);这能避免进度或评分超过业务范围。7.3 数字输入转换费用、人均等场景需要从字符串转数字。consttotalNumber(this.cost);constsplitMath.round(total/this.players);真实项目中还可以补充空值和非法值处理。八、活动记录类应用的体验原则8.1 首屏直接给答案用户打开 Murder Mystery Party 时应该立刻看到最关键的活动信息。例如主题、数量、进度、评分、地点或当前记录。8.2 操作入口要明确按钮文案应该短而直接。保存记录。增加数量。生成分配。投票或签到。推进步骤。这些动作都能在当前页面完成。8.3 反馈文字要具体反馈不应该只写“成功”。更好的方式是把用户刚刚编辑的字段带入结果。this.messagethis.scriptName updated;九、组件映射9.1 常用组件组件项目用途特点Text展示标题、状态和结果轻量TextInput编辑活动字段直接Button触发状态变化明确Row并列展示指标适合统计Grid四宫格展示信息适合卡片Scroll承载多输入内容适合小屏9.2 布局组合项目根据场景选择不同布局。有的页面使用四宫格有的页面使用左右分栏有的页面使用顶部大色块。这种差异让每个应用都有自己的使用节奏。9.3 信息密度兴趣活动工具要保持适中信息密度。太少会像便签太多会像表格系统。当前项目选择了单页工具的中间状态。十、可扩展数据模型10.1 抽象记录对象interfaceClubRecord{id:string;title:string;detail:string;count:number;updatedAt:number;}这个对象可以承载历史记录。10.2 数组状态Staterecords:ClubRecord[][];数组状态适合把当前单条记录扩展为列表。10.3 追加记录this.records[...this.records,{id:Date.now().toString(),title:this.scriptName,detail:this.players,count:1,updatedAt:Date.now()}];不可变追加方式更利于 UI 刷新。十一、持久化方向11.1 保存当前状态活动工具一旦真实使用就需要保存上一次记录。interfaceSavedClubState{currentTitle:string;currentDetail:string;records:ClubRecord[];version:number;}11.2 恢复默认值functionfallbackText(value:string|undefined):string{returnvalue||;}读取旧数据时要考虑字段缺失。11.3 数据升级加入version后后续字段扩展更稳。例如新增标签、地点坐标或附件信息时可以按版本迁移。十二、调试与验证12.1 验证状态变化Button(Debug).onClick((){console.info(value: this.scriptName);})先确认状态变化再看 UI 是否刷新。12.2 验证布局适配在小屏设备上重点看三个点。卡片文字是否过长。输入框是否完整可见。按钮是否被挤出屏幕。12.3 验证数字边界场景风险处理自增过快数字超出预期设置上限或业务条件空字符串转数字出现异常结果使用默认值长文本输入卡片被撑开使用滚动容器多字段同时变化反馈不清楚结果文案复述关键字段十三、工程化拆分13.1 抽离卡片组件BuilderfunctionInfoCard(label:string,value:string,color:string){Column({space:6}){Text(label).fontSize(14).fontColor(#6B7280)Text(value).fontSize(18).fontWeight(FontWeight.Bold)}.padding(16).backgroundColor(color).borderRadius(8)}卡片组件可以复用到统计、状态、活动摘要等区域。13.2 抽离格式化函数exportfunctionbuildMessage(title:string,detail:string):string{returntitle / detail;}格式化函数独立后页面组件会更清爽。13.3 抽离主题constTheme{pageBg:#FFFFFF,accent:#312E81,radius:8};统一主题方便继续扩展多个页面。十四、同类应用对比14.1 单页工具单页工具适合快速记录和即时反馈。Murder Mystery Party 当前就属于这种形态。14.2 多记录工具当记录量增加后可以加入历史列表。interfaceRecordGroup{date:string;items:ClubRecord[];}14.3 社群协作工具如果加入多人协作可以扩展成员、角色、报名和消息提醒。但当前版本已经具备最小可用闭环。十五、发布级技术亮点15.1 代码短但语义完整剧本推理聚会 的字段和按钮都能直接对应业务场景。这让读者可以从页面代码理解产品设计。15.2 反馈即时每次点击都会改变一个可见状态。这对移动端工具很关键。15.3 扩展路径清晰当前项目可以继续扩展历史记录、本地存储、附件、标签和统计图。先完成一个可用单页再扩展为完整社群工具是这类鸿蒙应用更自然的演进方式。十六、总结Murder Mystery Party 用 ArkTS 和 ArkUI 展示了一个 线下剧本活动 场景如何落成可运行页面。它通过State保存核心数据通过TextInput接收用户输入通过Button修改状态再用卡片、文字和数字反馈结果。从技术学习看它覆盖了状态管理、声明式布局、输入同步、按钮事件、条件计算和移动端适配。从产品场景看剧本推理聚会 把 维护剧本投票、角色分配、场地时间、总费用和人均分摊 这件事变得更轻、更清晰也更适合在手机端随手维护。相关资源HarmonyOS 应用开发文档ArkTS 语言基础ArkUI 声明式开发范式
