文章目录背景一、后台任务的生命周期二、三态状态机设计三、启动任务的状态管理四、停止任务的状态管理五、完整错误码解析5.1 启动时的错误码5.2 停止时的错误码六、Demo 中的错误提示实现七、UI 按钮状态与 taskStatus 联动八、状态显示九、任务 ID 的使用十、最佳实践总结正确做法错误做法十一、小结背景近期发现一款很有意思的HarmonyOS 三方库, 地址 pura/harmony-utils(V1.4.0) , 作者是桃花镇童长老, 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦案例demo导航展示↓↓↓↓↓↓接下来言归正传 ↓↓↓↓一、后台任务的生命周期一个 HarmonyOS 长时任务的完整生命周期如下[申请] startBackgroundRunning() ↓ [运行中] 系统通知栏显示持续通知 ↓ [结束] stopBackgroundRunning() 或 App 被销毁 ↓ [清理] 通知消失系统释放后台资源整个过程有三个关键时间点申请时调用startBackgroundRunning系统校验权限和模式运行时后台业务持续执行通知栏有标志销毁时调用stopBackgroundRunning或 App 进程结束二、三态状态机设计Demo 中使用taskStatus来精确管理任务状态避免重复操作StatetaskStatus:idle|running|stoppingidle;三个状态的含义状态说明允许的操作idle空闲没有运行中的长时任务可以启动running长时任务运行中可以停止stopping正在执行停止操作等待完成不允许其他操作状态转换图idle ──[startTask]──→ running ──[stopTask]──→ stopping ──[成功]──→ idle ↑ | └─────────────────[失败回滚]────────────────────────────────┘三、启动任务的状态管理asyncstartTask(){if(this.taskStatus!idle){return;// 防止重复启动}constselectedModesthis.getSelectedModes();if(selectedModes.length0){this.addLog(⚠️,请至少选择一种后台任务模式,warn);return;}this.taskStatusrunning;// 先设置状态防止用户重复点击this.taskId;this.addLog(,申请长时任务... 模式:${this.getModeNames(selectedModes)},info);this.addLog(,共${selectedModes.length}种模式,info);constrequest:TaskRequest{backgroundTaskModes:selectedModes,combinedTaskNotification:false,};try{constnotificationawaitBgTaskUtil.startBackgroundRunning(request);this.taskIdString(notification.continuousTaskId);this.taskStatusrunning;this.addLog(✅,长时任务启动成功! TaskId:${this.taskId},success);ToastUtil.showShort(后台任务已启动);}catch(e){consterreasBusinessError;this.taskStatusidle;// 失败时回滚状态lethint;if(err.code201){hint权限不足需要 KEEP_BACKGROUND_RUNNING 权限;}elseif(err.code16000007){hint服务忙并发任务冲突请稍后重试;}elseif(err.code16000151){hintWantAgent 配置无效;}else{hint错误码:${err.code};}this.addLog(❌,启动失败:${hint},error);ToastUtil.showShort(启动失败: hint);}}关键设计点先设置状态在await之前就把taskStatus设为running防止用户在异步等待期间重复点击失败回滚catch 中将状态回滚到idle否则 UI 会一直显示运行中无法再次启动四、停止任务的状态管理asyncstopTask(){if(this.taskStatusidle||this.taskStatusstopping){return;// 防止重复停止}this.taskStatusstopping;// 进入停止中状态this.addLog(⏹️,正在取消长时任务...,info);try{awaitBgTaskUtil.stopBackgroundRunning();this.addLog(✅,长时任务已取消,success);this.taskStatusidle;this.taskId;ToastUtil.showShort(后台任务已停止);}catch(e){consterreasBusinessError;this.taskStatusidle;// 停止失败也回到 idlethis.addLog(❌,取消失败: 错误码${err.code},error);ToastUtil.showShort(停止失败: err.code);}}为什么停止失败也回到idle而不是running因为stopBackgroundRunning失败大多是系统层面的问题反复重试通常也不会成功。回到idle状态允许用户重新尝试比卡在stopping状态好。五、完整错误码解析5.1 启动时的错误码错误码含义处理建议201权限被拒绝检查module.json5是否声明了KEEP_BACKGROUND_RUNNING401参数错误检查backgroundTaskModes数组是否为空或类型错误16000007服务繁忙并发任务冲突等待一段时间后重试16000151WantAgent 无效检查wantAgentInfo配置9800001内存操作失败系统资源不足稍后重试9800002数据写入 Parcel 失败参数有误检查 request 对象9800003内部事务失败系统内部错误9800004系统服务操作失败系统内部错误9800005长时任务校验失败申请模式与实际业务不符9800006通知校验失败通知配置有误9800007长时任务存储失败系统存储异常5.2 停止时的错误码同9800001~9800007含义相同。六、Demo 中的错误提示实现}catch(e){consterreasBusinessError;this.taskStatusidle;lethint;if(err.code201){hint权限不足需要 KEEP_BACKGROUND_RUNNING 权限;}elseif(err.code16000007){hint服务忙并发任务冲突请稍后重试;}elseif(err.code16000151){hintWantAgent 配置无效;}else{hint错误码:${err.code};}this.addLog(❌,启动失败:${hint},error);ToastUtil.showShort(启动失败: hint);}这里的设计将BusinessError的数字错误码转为对人类友好的文字描述同时记录到日志区方便调试和显示 Toast方便用户理解七、UI 按钮状态与 taskStatus 联动// 启动按钮Button(启动长时任务).layoutWeight(1).height(40).borderRadius(10).backgroundColor(this.canStartthis.taskStatusidle?#4080FF:#CCC).fontColor(#FFF).fontSize(13).enabled(this.canStartthis.taskStatusidle)// 只有 idle 且有选中模式才可用.onClick((){this.startTask();})// 停止按钮Button(停止任务).layoutWeight(1).height(40).borderRadius(10).margin({left:10}).backgroundColor(this.taskStatusrunning?#FF5252:#CCC).fontColor(#FFF).fontSize(13).enabled(this.taskStatusrunning)// 只有 running 状态才可停止.onClick((){this.stopTask();})完美的联动逻辑idle启动按钮蓝色可用停止按钮灰色禁用running启动按钮灰色禁用停止按钮红色可用stopping两个按钮都灰色禁用八、状态显示Text(this.taskStatusidle?⏸️ 空闲:this.taskStatusrunning? 运行中:⏳ 停止中...).fontSize(13).fontWeight(FontWeight.Bold).fontColor(this.taskStatusrunning?#00C853:this.taskStatusstopping?#FF9800:#888)三种状态的视觉区分idle空闲灰色 ⏸️running运行中绿色 stopping停止中橙色 ⏳九、任务 ID 的使用启动成功后系统会返回ContinuousTaskNotification其中包含continuousTaskIdconstnotificationawaitBgTaskUtil.startBackgroundRunning(request);this.taskIdString(notification.continuousTaskId);taskId用于日志追踪记录每次任务的唯一 ID便于排查问题未来扩展API21 支持按 ID 精确停止指定任务当前版本只能停止全部十、最佳实践总结正确做法申请前先验证选择了至少一种模式使用三态状态机防止重复操作在 catch 中区分错误码给用户友好提示失败时及时回滚状态业务完成后立即调用stopBackgroundRunning在aboutToDisappear或 Ability 销毁时确保停止任务错误做法不处理异常任务失败后界面卡死没有防重复逻辑用户连续点击导致申请多个任务任务完成后忘记停止白白浪费系统资源在模拟器上测试并因为不支持而以为代码有 bug十一、小结后台长时任务的状态管理看似简单启动/停止实际上需要精心处理三态状态机idle / running / stopping是关键先改状态后 await防止并发操作失败必须回滚让用户可以重试错误码转人话提升用户体验BgTaskUtil封装了底层细节而 Demo 页面则展示了如何在 UI 层正确管理这些状态——两者结合才构成完整的后台任务解决方案。
