企业官网建设流程全解析

HarmonyOS 实况窗服务闭环实战：创建、更新、点击与结束

实况窗（Live Window）是 HarmonyOS 中用于展示"正在进行中"服务的核心组件，适用于配送进度、打车状态、导航指引、排队等候、运动记录等场景。然而，若实现不当，容易出现以下问题：业务 ID 设计不当导致卡片更新错乱；点击回跳参数未校验，用户可能跳转到错误页面；服务结束后未清理本地状态，造成状态残留与堆积。
本文将以配送进度为示例场景，系统阐述实况窗服务的完整工程闭环：创建、更新、点击与结束。重点不在于罗列所有 API，而是将业务状态、卡片状态、点击回跳和清理动作进行清晰解耦，帮助读者将这一模式迁移到自身的服务类应用中。

1. 本文要解决的服务问题

问题	典型表现	工程处理
卡片更新错乱	A 订单进度覆盖 B 订单	使用稳定的业务 ID 关联状态
点击跳转错误页面	点击卡片后打开空白页或错误页	对 WantAgent 参数进行校验与兜底
服务结束后卡片仍显示	业务已完成，但实况窗未消失	结束时同步清理卡片与本地状态
异常难以追踪	用户反馈"未更新"，开发无日志可查	保留关键状态变更日志

2. 官方资料与适用边界

实况窗属于 HarmonyOS 服务体验能力的一部分。开发前，建议前往华为开发者文档中心，检索以下关键词以获取最新官方资料：

• 华为开发者文档中心：https://developer.huawei.com/consumer/cn/doc/
• HarmonyOS Guides：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
• 本文重点核验实况窗创建、更新、点击和结束链路，资料只作为能力边界参考。

本文示例边界：

3. 先定义业务任务，不要直接操作卡片

实况窗不是业务数据源，它只是服务状态的一种外显形式。先定义业务任务，后面创建、更新、结束都围绕同一个taskId。

// common/live/LiveTask.etsexporttypeLiveTaskStatus='created'|'running'|'finished'|'failed';exportinterfaceLiveTask{taskId:string;title:string;description:string;progress:number;status:LiveTaskStatus;updatedAt:number;}exportfunctionnormalizeProgress(value:number):number{if(value<0){return0;}if(value>100){return100;}returnvalue;}

代码解释：

4. 用 Store 保存本地状态

如果应用重启或服务更新失败，本地至少要知道当前有哪些进行中的任务。

// common/live/LiveViewStore.etsimport{LiveTask}from'./LiveTask';exportclassLiveViewStore{privatestatictasks:Map<string,LiveTask>=newMap();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(item=>item.status==='running'||item.status==='created');}}

这段 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{constcurrent=LiveViewStore.find(taskId);if(current===undefined){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.source==='live_view'&&params.taskId.length>0;}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{consttask=LiveViewStore.find(taskId);if(task===undefined){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(item=>item.taskId===taskId);}}

日志不要保存敏感详情，只保留任务 id、动作和时间。这样排查“没有更新”“点击没反应”“结束后还显示”时，有基本证据。

9. 验证清单

建议使用两个不同taskId连续测试，确认 A 任务不会覆盖 B 任务。

可以额外增加一份服务状态记录，用来对照业务侧和实况窗侧是否一致。比如业务状态已经finished，但本地 Store 仍能查到 running task，就说明清理闭环有问题。

import{LiveViewStore}from'./LiveViewStore';exportfunctionassertLiveTaskClosed(taskId:string):boolean{returnLiveViewStore.find(taskId)===undefined;}

这段断言函数适合放在调试或测试工具里，不建议作为正式业务判断。它帮助测试同学在服务结束后快速确认本地状态是否清理干净。

10. 实况窗排查表

11. 发布前检查

发布前最好准备三组任务：正常完成、异常失败、用户点击回跳。每组都记录 taskId、创建时间、最后一次更新时间和结束动作。实况窗问题往往出现在后台或锁屏场景，只有前台页面验证是不够的。

实况窗专项证据包：创建、更新、点击、结束必须成对

实况窗问题通常不是某一个 API 调用错了，而是生命周期没有闭环：创建后没有稳定taskId，更新时覆盖了别的任务，点击回跳缺参数，服务结束后本地状态还残留。补强时要让每个动作都有可核验记录。

interfaceLiveWindowEvidence{taskId:stringcreatedAt:numberupdatedVersion:numberclickRoute?:stringfinishedAt?:number}functionassertLiveWindowClosed(e:LiveWindowEvidence):void{if(!e.finishedAt)thrownewError(`实况窗未结束：${e.taskId}`)if(e.updatedVersion<1)thrownewError('实况窗没有更新记录')}

这段代码面向验收阶段，目标是证明服务外显状态和业务任务状态没有分叉。

12. 实况窗闭环总结

实况窗适合做服务状态外显，但不能把它当成业务状态本身。稳定的实现应该有四层：业务任务记录真实进度，Store 保存本地状态，Service 负责创建和更新，ClickRouter 处理点击回跳。最后用 finish 清理闭环，才能避免服务卡片变成难排查的后台状态。