文章目录前言一、为什么需要后台长时任务二、BgTaskUtil 是什么三、核心 API 详解3.1 startBackgroundRunning3.2 stopBackgroundRunning四、内部实现原理五、权限配置六、完整 Demo 演示6.1 数据结构定义6.2 组件状态6.3 获取选中的模式6.4 启动长时任务6.5 停止长时任务七、运行效果八、注意事项九、小结前言近期发现一款很有意思的HarmonyOS 三方库, 地址 pura/harmony-utils(V1.4.0) , 作者是桃花镇童长老, 我这里也是直接通过该作者公布的源码进行案例编写进行,写了到目前写了一部分demo ,感觉确实很有帮助,这里呢也是开始写一个系列的演示demo 供大家参考。如有帮助可以在OpenHarmony中进行下载安装进行使用哦案例demo导航展示↓↓↓↓↓↓接下来言归正传 ↓↓↓↓一、为什么需要后台长时任务我们在日常开发 App 时经常会遇到这样的需求用户切换到后台音乐播放器依然要继续播放歌曲导航 App 在后台持续更新定位信息下载工具在后台继续下载大文件VoIP 电话 App 保持通话连接不断线这些场景有一个共同点——应用切入后台后业务逻辑必须继续运行。在 HarmonyOS 中系统为了节省电量会对后台应用进行资源回收。如果不申请长时任务应用切到后台一段时间后业务就会被系统暂停。长时任务Continuous Task允许有实际后台业务需要如音视频播放、定位等的应用在后台持续运行系统会在通知栏显示一条持续通知告知用户该应用正在后台活动。二、BgTaskUtil 是什么BgTaskUtil是对 HarmonyOSkit.BackgroundTasksKit中backgroundTaskManager模块的封装将底层繁琐的 API 调用简化为两个核心方法// 申请长时任务staticasyncstartBackgroundRunning(request:TaskRequest):PromisebackgroundTaskManager.ContinuousTaskNotification// 取消长时任务staticasyncstopBackgroundRunning(context?:Context):Promisevoid使用BgTaskUtil你不需要手动构造 WantAgent、转换任务模式字符串——这些繁琐工作都由工具类内部完成。三、核心 API 详解3.1 startBackgroundRunningstaticasyncstartBackgroundRunning(request:TaskRequest):PromisebackgroundTaskManager.ContinuousTaskNotification参数说明TaskRequest接口定义字段类型必填说明backgroundTaskModesBackgroundTaskMode[]是后台任务模式数组可多选最多 10 个backgroundTaskSubmodesBackgroundTaskSubMode[]否子模式API21combinedTaskNotificationboolean否是否合并通知默认 falsecontinuousTaskIdnumber否任务 IDAPI21-1 表示新建contextContext否上下文默认使用AppUtil.getContext()wantAgentInfowantAgent.WantAgentInfo否点击通知后的行为默认跳转 EntryAbility返回值ContinuousTaskNotification对象包含continuousTaskId系统分配的长时任务唯一 ID异常BusinessError错误码说明201权限不足需声明ohos.permission.KEEP_BACKGROUND_RUNNING16000007服务忙存在并发任务冲突稍后重试16000151WantAgent 配置无效9800005长时任务校验失败9800006通知校验失败3.2 stopBackgroundRunningstaticasyncstopBackgroundRunning(context?:Context):Promisevoid取消已申请的长时任务通知栏的持续通知也会随之消失。context可选默认使用全局 Context。四、内部实现原理BgTaskUtil内部的startBackgroundRunning做了三件事获取 Context优先使用传入的 context否则调用AppUtil.getContext()获取全局上下文转换任务模式将枚举值BackgroundTaskMode转为系统识别的字符串如MODE_AUDIO_PLAYBACK→audioPlayback构造 WantAgent创建默认的 WantAgent点击通知后跳转 EntryAbility再调用底层 APIstaticasyncstartBackgroundRunning(request:TaskRequest):PromisebackgroundTaskManager.ContinuousTaskNotification{constcontext:Contextrequest?.context??AppUtil.getContext();constbgModes:string[]BgTaskUtil.convertTaskModes(request.backgroundTaskModes);constwantAgentObj:WantAgentawaitBgTaskUtil.getDefaultWantAgent(request?.wantAgentInfo);consttaskNotificationawaitbackgroundTaskManager.startBackgroundRunning(context,bgModes,wantAgentObj);returntaskNotification;}五、权限配置在module.json5中声明权限{ module: { requestPermissions: [ { name: ohos.permission.KEEP_BACKGROUND_RUNNING } ] } }注意KEEP_BACKGROUND_RUNNING是 restricted 权限需要向华为申请授权普通开发者测试时可能无法在模拟器上使用建议使用真机测试。六、完整 Demo 演示以下代码来自BgTaskDemoPage.ets展示了完整的启动/停止长时任务流程效果演示6.1 数据结构定义import{BgTaskUtil}from../Utils/BgTaskUtil;import{TaskRequest}from../Utils/entity/TaskRequest;import{backgroundTaskManager}fromkit.BackgroundTasksKit;import{ToastUtil}from../Utils/action/ToastUtil;import{BusinessError}fromkit.BasicServicesKit;interfaceBgModeItem{label:string;mode:backgroundTaskManager.BackgroundTaskMode;desc:string;selected:boolean;}6.2 组件状态EntryComponentstruct BgTaskDemoPage{Statemodes:BgModeItem[][{label: 数据传输,mode:backgroundTaskManager.BackgroundTaskMode.MODE_DATA_TRANSFER,desc:下载/上传,selected:false},{label: 音视频播放,mode:backgroundTaskManager.BackgroundTaskMode.MODE_AUDIO_PLAYBACK,desc:后台音乐,selected:false},{label:️ 录音录屏,mode:backgroundTaskManager.BackgroundTaskMode.MODE_AUDIO_RECORDING,desc:后台录制,selected:false},{label: 定位导航,mode:backgroundTaskManager.BackgroundTaskMode.MODE_LOCATION,desc:导航定位,selected:false},{label: 蓝牙业务,mode:backgroundTaskManager.BackgroundTaskMode.MODE_BLUETOOTH_INTERACTION,desc:蓝牙数据传输,selected:false},{label: 多设备互联,mode:backgroundTaskManager.BackgroundTaskMode.MODE_MULTI_DEVICE_CONNECTION,desc:设备发现/连接,selected:false},{label: 音视频通话,mode:backgroundTaskManager.BackgroundTaskMode.MODE_VOIP,desc:VoIP通话,selected:false},{label:⚙️ 计算任务,mode:backgroundTaskManager.BackgroundTaskMode.MODE_TASK_KEEPING,desc:后台计算,selected:true},{label: 多媒体业务,mode:backgroundTaskManager.BackgroundTaskMode.MODE_AV_PLAYBACK_AND_RECORD,desc:音视频处理,selected:false},{label:⚡ 特殊场景,mode:backgroundTaskManager.BackgroundTaskMode.MODE_SPECIAL_SCENARIO_PROCESSING,desc:特殊场景,selected:false},];StatetaskStatus:idle|running|stoppingidle;StatetaskId:string;StatecanStart:booleanfalse;6.3 获取选中的模式getSelectedModes():backgroundTaskManager.BackgroundTaskMode[]{constselected:backgroundTaskManager.BackgroundTaskMode[][];for(leti0;ithis.modes.length;i){if(this.modes[i].selected){selected.push(this.modes[i].mode);}}returnselected;}6.4 启动长时任务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);}}6.5 停止长时任务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;this.addLog(❌,取消失败: 错误码${err.code},error);ToastUtil.showShort(停止失败: err.code);}}七、运行效果页面加载后底部日志区域会出现[初始化] 后台任务演示页面已加载 [说明] 模拟器/部分设备可能不支持请使用真机测试选择⚙️ 计算任务模式后点击启动长时任务[] 申请长时任务... 模式: TASK_KEEPING [] 共 1 种模式 [✅] 长时任务启动成功! TaskId: 12345通知栏会出现系统持续通知提示后台任务正在运行。点击停止任务[⏹️] 正在取消长时任务... [✅] 长时任务已取消八、注意事项必须使用真机测试模拟器不支持长时任务权限需要华为审核KEEP_BACKGROUND_RUNNING是 restricted 权限正式上架需申请模式需与业务匹配选择的BackgroundTaskMode必须与实际业务一致系统会校验一个 UIAbility 最多 10 个并发长时任务超出会报9800005错误停止任务要及时业务完成后必须调用stopBackgroundRunning避免浪费系统资源九、小结方法说明startBackgroundRunning(request)申请长时任务返回任务通知对象含 taskIdstopBackgroundRunning(context?)取消长时任务通知栏通知同步消失BgTaskUtil将后台任务的申请流程封装为简单的两步操作开发者只需关心业务逻辑选择模式 → 构造 TaskRequest → 调用 startBackgroundRunning不需要深入了解底层 WantAgent 和任务模式字符串的转换细节。
