HarmonyOS 实况窗服务闭环实战创建、更新、点击与结束实况窗Live Window是 HarmonyOS 中用于展示正在进行中服务的核心组件适用于配送进度、打车状态、导航指引、排队等候、运动记录等场景。然而若实现不当容易出现以下问题业务 ID 设计不当导致卡片更新错乱点击回跳参数未校验用户可能跳转到错误页面服务结束后未清理本地状态造成状态残留与堆积。本文将以配送进度为示例场景系统阐述实况窗服务的完整工程闭环创建、更新、点击与结束。重点不在于罗列所有 API而是将业务状态、卡片状态、点击回跳和清理动作进行清晰解耦帮助读者将这一模式迁移到自身的服务类应用中。1. 本文要解决的服务问题问题典型表现工程处理卡片更新错乱A 订单进度覆盖 B 订单使用稳定的业务 ID 关联状态点击跳转错误页面点击卡片后打开空白页或错误页对 WantAgent 参数进行校验与兜底服务结束后卡片仍显示业务已完成但实况窗未消失结束时同步清理卡片与本地状态异常难以追踪用户反馈未更新开发无日志可查保留关键状态变更日志2. 官方资料与适用边界实况窗属于 HarmonyOS 服务体验能力的一部分。开发前建议前往华为开发者文档中心检索以下关键词以获取最新官方资料华为开发者文档中心https://developer.huawei.com/consumer/cn/doc/HarmonyOS Guideshttps://developer.huawei.com/consumer/cn/doc/harmonyos-guides/本文重点核验实况窗创建、更新、点击和结束链路资料只作为能力边界参考。本文示例边界项目说明技术栈HarmonyOS NEXT、ArkTS、Stage 模型业务场景配送、打车、预约、运动、排队等持续型服务核心对象业务任务LiveTask、实况窗状态、点击回跳参数注意事项具体 API 名称、调用方式及权限要求请以当前官方文档为准3. 先定义业务任务不要直接操作卡片实况窗不是业务数据源它只是服务状态的一种外显形式。先定义业务任务后面创建、更新、结束都围绕同一个taskId。// common/live/LiveTask.etsexporttypeLiveTaskStatuscreated|running|finished|failed;exportinterfaceLiveTask{taskId:string;title:string;description:string;progress:number;status:LiveTaskStatus;updatedAt:number;}exportfunctionnormalizeProgress(value:number):number{if(value0){return0;}if(value100){return100;}returnvalue;}代码解释点说明职责边界描述业务服务状态不直接依赖实况窗 API输入约束taskId必须稳定progress必须归一化避免的问题防止进度越界和多任务互相覆盖下一层连接Store 和 Service 都围绕LiveTask工作4. 用 Store 保存本地状态如果应用重启或服务更新失败本地至少要知道当前有哪些进行中的任务。// common/live/LiveViewStore.etsimport{LiveTask}from./LiveTask;exportclassLiveViewStore{privatestatictasks:Mapstring,LiveTasknewMap();staticsave(task:LiveTask):void{LiveViewStore.tasks.set(task.taskId,task);}staticfind(taskId:string):LiveTask|undefined{returnLiveViewStore.tasks.get(taskId);}staticremove(taskId:string):void{LiveViewStore.tasks.delete(taskId);}staticrunningTasks():LiveTask[]{returnArray.from(LiveViewStore.tasks.values()).filter(itemitem.statusrunning||item.statuscreated);}}这段 Store 的边界是本地任务状态。它不负责展示也不负责点击回跳。好处是当实况窗创建失败、更新失败或应用重新进入时仍然能从一个地方恢复服务状态。5. 创建实况窗时要建立关联创建实况窗不能只传标题和进度还要建立业务 id 与卡片状态的关系。下面示例用接口占位表示平台创建动作读者接入时替换为当前官方 API。// common/live/LiveViewService.etsimport{LiveTask,normalizeProgress}from./LiveTask;import{LiveViewStore}from./LiveViewStore;exportclassLiveViewService{staticcreateDeliveryTask(taskId:string,title:string):LiveTask{consttask:LiveTask{taskId,title,description:配送员正在前往商家,progress:10,status:created,updatedAt:Date.now()};LiveViewStore.save(task);// TODO: 接入实况窗创建 API使用 taskId 作为业务关联键。returntask;}staticupdateProgress(taskId:string,progress:number,description:string):LiveTask|undefined{constcurrentLiveViewStore.find(taskId);if(currentundefined){returnundefined;}constnext:LiveTask{...current,progress:normalizeProgress(progress),description,status:running,updatedAt:Date.now()};LiveViewStore.save(next);// TODO: 接入实况窗更新 API只更新进度和文案。returnnext;}}这里的关键是taskId。它防止多个服务卡片互相覆盖也方便点击回跳时找到正确页面。6. 点击回跳参数必须可校验实况窗点击通常要回到应用内详情页。回跳参数不能直接信任至少要校验业务类型和 id。// common/live/LiveClickRouter.etsexportinterfaceLiveClickParams{taskId:string;source:live_view;target:delivery_detail|task_list;}exportclassLiveClickRouter{staticisValid(params:LiveClickParams):boolean{returnparams.sourcelive_viewparams.taskId.length0;}staticfallback():LiveClickParams{return{taskId:,source:live_view,target:task_list};}}这段代码的作用是把点击参数变成可验证对象。它防止点击卡片后因为参数缺失直接打开空白详情页。实际项目中可以在UIAbility.onCreate或路由入口处统一解析。7. 服务结束时同时清理卡片和本地状态服务完成后如果只改 UI不清理本地状态后续恢复任务时会读到旧数据。// common/live/LiveViewFinishService.etsimport{LiveViewStore}from./LiveViewStore;exportclassLiveViewFinishService{staticfinish(taskId:string):boolean{consttaskLiveViewStore.find(taskId);if(taskundefined){returnfalse;}// TODO: 接入实况窗结束 API让卡片退出进行中状态。LiveViewStore.remove(taskId);returntrue;}}这段代码只做结束闭环。输入是业务 id输出是是否找到并清理。它防止“服务已经完成但本地仍认为在进行中”的状态漂移。8. 增加状态日志方便排查实况窗问题经常出现在用户锁屏或后台状态下日志很重要。// common/live/LiveViewLog.etsexportinterfaceLiveViewLogItem{taskId:string;action:create|update|click|finish;at:number;note:string;}exportclassLiveViewLog{privatestaticlogs:LiveViewLogItem[][];staticrecord(taskId:string,action:LiveViewLogItem[action],note:string):void{LiveViewLog.logs.push({taskId,action,at:Date.now(),note});}staticquery(taskId:string):LiveViewLogItem[]{returnLiveViewLog.logs.filter(itemitem.taskIdtaskId);}}日志不要保存敏感详情只保留任务 id、动作和时间。这样排查“没有更新”“点击没反应”“结束后还显示”时有基本证据。9. 验证清单验证动作预期结果创建配送任务实况窗出现初始状态连续更新进度文案和进度只更新当前任务点击实况窗回到正确详情页参数缺失点击回到列表兜底页服务结束卡片结束本地状态清理建议使用两个不同taskId连续测试确认 A 任务不会覆盖 B 任务。可以额外增加一份服务状态记录用来对照业务侧和实况窗侧是否一致。比如业务状态已经finished但本地 Store 仍能查到 running task就说明清理闭环有问题。import{LiveViewStore}from./LiveViewStore;exportfunctionassertLiveTaskClosed(taskId:string):boolean{returnLiveViewStore.find(taskId)undefined;}这段断言函数适合放在调试或测试工具里不建议作为正式业务判断。它帮助测试同学在服务结束后快速确认本地状态是否清理干净。10. 实况窗排查表现象可能原因检查方法修复建议卡片不更新taskId 不一致查看状态日志创建和更新使用同一业务 id点击空白页参数缺失打印 click params增加参数校验和兜底完成后仍显示只清理业务状态查 finish 调用同时结束卡片和 Store多任务错乱用单例保存当前任务创建两个任务复测按 taskId 分桶管理用户反馈无证据没有日志查看本地记录记录 create/update/click/finish11. 发布前检查检查项判定每个实况窗都有稳定业务 id不用随机临时值点击回跳参数可校验缺失时有兜底更新只改必要字段不重复创建卡片服务结束有清理动作本地状态不残留两个并发任务测过不互相覆盖发布前最好准备三组任务正常完成、异常失败、用户点击回跳。每组都记录 taskId、创建时间、最后一次更新时间和结束动作。实况窗问题往往出现在后台或锁屏场景只有前台页面验证是不够的。发布验证组关注点正常完成进度更新、点击回跳、结束清理异常失败文案更新、失败状态、用户提示并发任务taskId 隔离不互相覆盖后台场景卡片可见回跳参数不丢实况窗专项证据包创建、更新、点击、结束必须成对实况窗问题通常不是某一个 API 调用错了而是生命周期没有闭环创建后没有稳定taskId更新时覆盖了别的任务点击回跳缺参数服务结束后本地状态还残留。补强时要让每个动作都有可核验记录。动作证据字段核验目标创建taskId、createdAt业务任务和实况窗一一对应更新version、progress不重复创建点击route、params可回到正确详情页结束finishedAt本地状态清理interfaceLiveWindowEvidence{taskId:stringcreatedAt:numberupdatedVersion:numberclickRoute?:stringfinishedAt?:number}functionassertLiveWindowClosed(e:LiveWindowEvidence):void{if(!e.finishedAt)thrownewError(实况窗未结束${e.taskId})if(e.updatedVersion1)thrownewError(实况窗没有更新记录)}这段代码面向验收阶段目标是证明服务外显状态和业务任务状态没有分叉。12. 实况窗闭环总结实况窗适合做服务状态外显但不能把它当成业务状态本身。稳定的实现应该有四层业务任务记录真实进度Store 保存本地状态Service 负责创建和更新ClickRouter 处理点击回跳。最后用 finish 清理闭环才能避免服务卡片变成难排查的后台状态。