鸿蒙 ArkTS 实战Weekly Review 从状态建模到办公交互完整解析前言周复盘 是一个面向团队协作与项目管理的鸿蒙 ArkTS 应用。按类型记录本周成果、问题和下周计划并支持导出复盘模板。 本文基于 entry/src/main/ets/pages/Index.ets 的真实代码结构展开重点分析interface 数据模型、State 状态、业务方法、Builder 组件和页面布局形成一篇可直接发布的技术解析。图示说明页面以办公场景为核心通过卡片、输入框、筛选按钮、统计信息和状态动作完成闭环。一、应用定位与业务闭环1.1 场景定位Weekly Review 的目标不是复杂后台系统而是把高频办公动作压缩到一个单页工具中。用户打开页面后可以查看当前状态、录入新记录、切换筛选条件并通过按钮推进状态。业务环节页面表现技术实现记录数据列表卡片ForEach 渲染新增内容输入框与按钮TextInput onClick状态管理标签、开关、文案State 驱动统计反馈数量、进度、提醒private 方法派生视觉组织卡片化结构Builder 复用1.2 代码阅读路径先看接口确认业务对象包含哪些字段。再看状态确认哪些数据会触发页面刷新。接着看方法确认新增、筛选、推进、导出等逻辑。最后看 Builder确认重复 UI 如何复用。核心判断轻量办公工具的工程质量取决于状态链路是否清晰而不是页面控件数量。二、工程结构与入口文件2.1 核心目录项目为鸿蒙 ArkTS 工程核心页面位于 entry/src/main/ets/pages/Index.ets。Weekly Review ├── AppScope ├── entry │ └── src │ └── main │ ├── ets │ │ └── pages │ │ └── Index.ets │ └── module.json5 ├── hvigor ├── build-profile.json5 └── oh-package.json52.2 页面入口ArkTS 使用 Entry 和 Component 定义页面入口。EntryComponentstruct Index{build(){Scroll(){Column(){// 页面主体}}}}2.3 技术要素技术点作用本项目价值ArkTS类型、状态、方法组织业务逻辑ArkUI声明式 UI构建页面结构State响应式状态驱动刷新BuilderUI 片段复用降低重复代码Hvigor构建系统生成应用包三、数据模型设计3.1 接口清单源码中的接口包括$iface。这些接口是列表渲染、状态推进和统计计算的基础。interfaceReviewItem{id:number;title?:string;name?:string;status?:string;done?:boolean;}实际源码会根据业务场景使用更明确字段例如议程、记录、设备、印章、用品、里程碑、成员、链接、账号或竞品等。3.2 字段角色字段类型常见字段作用标识字段id列表 key 与操作目标标题字段itle、ame卡片主信息分类字段ype、 ag、status筛选与颜色映射数值字段count、progress、seconds统计与进度状态字段done、confirmed、ctive控制按钮和文案3.3 建模收益使用接口可以把页面数据结构固定下来避免 UI 渲染时字段来源不明确。对于后续接入本地存储或接口数据也更容易做序列化转换。四、State 状态拆解4.1 状态清单项目中的状态包括$state。Staterecords:ReviewItem[][];StatedraftText:string;Statefilter:string全部;Statemessage:string;不同项目的命名不同但模式一致列表保存业务对象草稿字段接收输入筛选字段控制视图消息字段反馈操作结果。4.2 状态分类状态类别示例说明列表状态$primaryState保存主业务数据输入状态draft、draftTopic、draftTitle录入新数据筛选状态ilter、 ag、selectedType控制可见列表反馈状态message、exportText、eminderText输出操作结果运行状态emainingSeconds、presentationMode控制当前运行表现4.3 状态更新策略列表更新建议使用新数组替换保证响应式刷新稳定。privateupdateRecord(id:number):void{this.recordsthis.records.map((item:ReviewItem){if(item.id!id){returnitem;}return{...item,done:!item.done};});}五、核心方法解析5.1 方法清单源码中的核心方法包括$method。方法类型典型方法作用查询方法isible、 iltered根据筛选状态返回列表新增方法ddItem、ddRecord创建新记录推进方法dvance、 oggle、confirm改变业务状态统计方法vg、count、 otal顶部指标展示反馈方法export、otify、saveShare输出操作结果5.2 新增逻辑新增方法通常从输入状态读取文本做空值判断然后追加到列表。privateaddRecord():void{consttitlethis.draftText.trim();if(title.length0){return;}constrecord:ReviewItem{id:Date.now(),title:title,done:false};this.records[record,...this.records];this.draftText;}5.3 筛选逻辑筛选方法把分类状态和列表数据组合起来。privatevisibleRecords():ReviewItem[]{returnthis.records.filter((item:ReviewItem){returnthis.filter全部||item.statusthis.filter;});}5.4 状态推进状态推进不要直接修改数组中的旧对象使用 map 生成新对象更稳。privatenext(id:number):void{this.recordsthis.records.map((item:ReviewItem){returnitem.idid?{...item,status:已处理}:item;});}六、Builder 组件复用6.1 Builder 清单源码中的 Builder 组件包括$builder。Builderprivatecard(item:ReviewItem){Column(){Text(item.title??item.name??未命名).fontSize(16).fontWeight(FontWeight.Bold)}.padding(14).backgroundColor(#FFFFFF).borderRadius(8)}6.2 复用范围组件片段复用原因card列表项结构稳定abs筛选按钮状态一致gendaCard议程卡片重复渲染qrMark小状态标记可复用columnView看板列结构一致6.3 分工边界Builder 负责界面片段不承担复杂业务计算。复杂逻辑放到 private 方法中页面更容易维护。七、页面布局结构7.1 纵向布局办公类应用通常使用 Scroll Column能容纳统计、表单、筛选和列表。Scroll(){Column(){// 概览区// 操作区// 列表区}.padding(16)}.height(100%).width(100%)7.2 信息分区区域内容价值顶部概览标题、说明、指标快速理解当前状态输入区域新增记录降低录入成本筛选区域类型、标签、状态控制信息范围列表区域卡片和操作按钮处理具体事项反馈区域导出、提醒、消息确认操作结果7.3 ForEach 渲染ForEach(this.records,(item:ReviewItem){this.card(item)},(item:ReviewItem)item.id.toString())稳定 key 有助于列表刷新时保持条目对应关系。八、交互链路8.1 输入链路TextInput({text:this.draftText}).onChange((value:string){this.draftTextvalue;})输入框只负责写入草稿状态不直接操作列表。8.2 按钮链路Button(添加).onClick((){this.addRecord();})按钮调用方法方法更新状态页面自动刷新。8.3 反馈链路privatesetMessage(text:string):void{this.messagetext;}反馈状态适合展示导出成功、提醒已设置、记录已更新等结果。实践要点不要让 UI 组件直接散落业务规则。组件触发方法方法更新状态是更稳定的链路。九、业务状态与颜色语义9.1 状态分类状态推荐颜色说明正常绿色已完成、已确认、已归还处理中蓝色当前任务、当前议程、主操作待处理橙色需要关注但未异常风险红色超时、低库存、未确认辅助灰色次要说明9.2 文案表达办公工具的文案要直接表达动作和状态例如“添加”“确认”“导出”“推进”“已借出”“待审批”。9.3 卡片信息密度每张卡片应包含三类信息主标题用户首先识别的对象。状态标签当前处理阶段。操作按钮下一步能做什么。十、运行与调试10.1 DevEco Studio 运行# 使用 DevEco Studio 打开项目# 同步依赖# 选择 entry 模块# 运行到模拟器或真机10.2 Hvigor 构建hvigorw clean hvigorw assembleHap10.3 调试关注点项目检查内容输入框onChange 是否写入状态新增按钮空输入是否被拦截列表刷新数组是否被新数组替换筛选按钮当前标签是否高亮统计指标是否从当前列表派生十一、可维护性分析11.1 文件规模当前 Index.ets 约 86 行适合作为单页示例。超过这个规模后可以拆分卡片组件、表单组件和统计组件。11.2 状态数量控制能从列表计算出来的值不必额外保存为 State。这样可以减少状态不一致。privateactiveCount():number{returnthis.records.filter((item:ReviewItem)!item.done).length;}11.3 命名一致性源码中的 $primaryMethod 体现了业务动作命名。方法名保持动词开头可以降低维护成本。十二、扩展方向12.1 本地存储可以把主列表持久化到本地重新打开页面时恢复。interfaceStoredItem{id:number;payload:string;updatedAt:number;}12.2 搜索能力当记录数量增加后可以引入关键词搜索并和现有筛选状态组合。12.3 导出能力办公场景常需要导出文本、表格或截图。当前方法层已经有消息状态或导出动作可以继续扩展。十三、同类模板抽象13.1 数据模板interfaceOfficeItem{id:number;title:string;status:string;}13.2 状态模板Stateitems:OfficeItem[][];StatedraftTitle:string;Statefilter:string全部;13.3 UI 模板BuilderprivateitemCard(item:OfficeItem){Row(){Text(item.title).layoutWeight(1)Text(item.status)}.padding(12).backgroundColor(#FFFFFF)}十四、实现亮点14.1 模型明确Weekly Review 使用 $iface 描述业务对象列表渲染和操作方法都有明确类型依据。14.2 状态集中$state 覆盖了页面交互所需的核心状态调试时可以直接定位状态入口。14.3 组件复用$builder 把重复 UI 抽出来页面结构更清楚。十五、总结Weekly Review 是一个典型的鸿蒙 ArkTS 办公小工具。它通过 $iface 建模业务数据通过 $state 保存页面状态通过 $method 完成新增、筛选、推进和反馈再通过 $builder 构建统一的卡片与操作区域。这类应用的实现重点是数据链路输入进入状态方法更新列表列表驱动 UI统计从源数据派生。掌握这套结构后可以快速扩展出更多办公看板、登记表、提醒器和轻量管理工具。如果这篇文章对你有帮助欢迎点赞、收藏、关注你的支持是我持续创作的动力相关资源HarmonyOS DeveloperArkTS 语言基础ArkUI 声明式开发DevEco StudioStage 模型应用包结构HarmonyOS 应用开发指南