引言想象一个场景你正在用手机导航屏幕自动熄灭了。或者你正在传输一个大文件到 NAS锁屏后传输中断了。这些都是因为系统为了省电在用户不操作一段时间后自动进入休眠状态。HarmonyOS NEXT 提供了ohos.runningLock模块来解决这个问题——它允许应用向系统申请一个运行锁在持锁期间系统不会进入休眠。这对于导航、文件传输、音乐播放、视频通话等需要后台持续运行的场景至关重要。本文将通过运行锁实验室Demo深入讲解ohos.runningLock的三种运行锁类型、创建-持有-释放的生命周期管理以及权限配置的完整流程。ohos.runningLock 模块概述ohos.runningLock是 HarmonyOS NEXT 提供的后台运行保障机制位于kit.BasicServicesKit。它的核心思想很简单应用向系统申请一把锁持锁期间系统不进入休眠锁超时后自动释放系统恢复正常的休眠策略。导入方式importrunningLockfromohos.runningLock;API 总览API返回值类型说明isSupported(type)boolean同步检测设备是否支持某类运行锁create(name, type)PromiseRunningLock异步创建一个运行锁对象RunningLock.hold(timeout)void同步持锁阻止休眠 timeout 毫秒RunningLock.unhold()void同步释放运行锁RunningLock.isHolding()boolean同步当前是否正在持锁三种运行锁类型枚举值含义场景API 要求BACKGROUND(1)后台运行锁保持 CPU 运行防止系统休眠API 10 起废弃PROXIMITY_SCREEN_CONTROL(2)距离感应亮灭屏通话时靠近耳朵熄屏拿远亮屏—BACKGROUND_USER_IDLE(129)用户空闲防休眠用户闲置时仍保持运行API 23 起类型选择指南普通 App 的防休眠需求 → 使用BACKGROUNDAPI 9 设备或BACKGROUND_USER_IDLEAPI 23通话类应用 → 使用PROXIMITY_SCREEN_CONTROL实现智能亮灭屏BACKGROUND已废弃但仍在广泛使用BACKGROUND_USER_IDLE是更精确的替代方案核心 API 详解1. isSupported() — 检测类型支持functionisSupported(type:RunningLockType):boolean;在创建运行锁之前应该先检测目标类型是否被当前设备支持。这个 API 不需要任何权限同步返回。constbgSupported:booleanrunningLock.isSupported(runningLock.RunningLockType.BACKGROUND);if(!bgSupported){console.warn(当前设备不支持 BACKGROUND 类型运行锁);return;}为什么需要检测不同类型的运行锁依赖不同的硬件和系统能力。例如PROXIMITY_SCREEN_CONTROL依赖距离传感器——如果设备没有距离传感器如部分平板这种类型就不支持。2. create() — 创建运行锁对象functioncreate(name:string,type:RunningLockType):PromiseRunningLock;创建运行锁需要两个参数name运行锁的名称建议使用包名/类名 用途的格式如com.example.app.NavigationLocktype运行锁类型重要create()返回Promise并且需要ohos.permission.RUNNING_LOCK权限。没有权限时 Promise 会 reject。runningLock.create(MyAppBgLock,runningLock.RunningLockType.BACKGROUND).then((lock:runningLock.RunningLock){this.rllock;console.log(运行锁创建成功);}).catch((err:Error){console.error(创建失败: err.message);// 可能是权限被拒绝});3. RunningLock.hold() — 持锁hold(timeout:number):void;持锁是核操作——调用后系统在timeout毫秒内不会进入休眠。超时后锁自动释放。// 持锁 5 分钟this.rl.hold(5*60*1000);// 持锁 30 分钟导航场景this.rl.hold(30*60*1000);超时设计的意义运行锁不是永久的——hold()必须指定一个超时时间。这个设计有两个目的防止应用忘记释放运行锁导致设备永远不眠、电量耗尽让开发者明确思考我需要多长时间的后台运行如果你需要持续防休眠应该在超时前重新调用hold()续期。4. RunningLock.unhold() — 释放锁unhold():void;任务完成后应主动释放运行锁让系统恢复正常的休眠策略。这是在节省用户电量。// 文件传输完成释放运行锁this.rl.unhold();console.log(运行锁已释放系统可正常休眠);5. RunningLock.isHolding() — 检查持锁状态isHolding():boolean;同步检测当前运行锁是否处于持有状态。if(this.rl.isHolding()){console.log(当前正在持锁系统不会休眠);}else{console.log(运行锁已释放或未持锁);}完整的生命周期管理运行锁的生命周期有四个阶段创建 → 持有 → 释放 → 销毁。每个阶段都需要正确的错误处理和状态跟踪privaterl:runningLock.RunningLock|nullnull;// 阶段 1创建privatecreateLock():void{if(this.rl!null){return;// 已存在不重复创建}runningLock.create(DemoLock,runningLock.RunningLockType.BACKGROUND).then((lock:runningLock.RunningLock){this.rllock;this.lockCreatedtrue;}).catch((err:Error){this.addLog(创建失败: err.message);});}// 阶段 2持有privateholdLock():void{if(this.rlnull){return;}try{this.rl.hold(300000);// 5 分钟this.isHoldingtrue;}catch(e){this.addLog(持锁失败);}}// 阶段 3释放privatereleaseLock():void{if(this.rlnull){return;}try{this.rl.unhold();this.isHoldingfalse;}catch(e){this.addLog(释放失败);}}// 阶段 4销毁privatedestroyLock():void{this.releaseLock();this.rlnull;this.lockCreatedfalse;}// 页面销毁时清理aboutToDisappear():void{this.destroyLock();}实战运行锁实验室页面结构┌─────────────────────────────────┐ │ 运行锁实验室 ohos.runningLock│ ← 标题栏#0EA5E9 天蓝 ├─────────────────────────────────┤ │ 运行锁类型支持 │ │ ┌─────────────────────────┐ │ │ │ ● BACKGROUND (后台运行) ✓ │ ← 三种类型检测结果 │ │ ● PROXIMITY_SCREEN ✓ │ │ │ ● BACKGROUND_USER_IDLE ✓ │ │ └─────────────────────────┘ │ ├─────────────────────────────────┤ │ 运行锁控制 │ │ ┌─────────────────────────┐ │ │ │ ● 运行锁已创建未持有 ⏱ 30s│ ← 状态 倒计时 │ │ ─────────────────────── │ │ │ │ 持锁时长: 1分 5分 15分 30分│ ← 时长选择 │ │ [持有 Hold] [销毁] │ │ ← 操作按钮按状态变 │ └─────────────────────────┘ │ ├─────────────────────────────────┤ │ 权限说明 │ ← module.json5 配置示例 ├─────────────────────────────────┤ │ 操作日志 │ └─────────────────────────────────┘倒计时机制Demo 中实现了持锁倒计时——当用户持锁后界面上显示剩余秒数超时后自动更新状态privatestartCountdown(seconds:number):void{this.clearCountdown();this.countdownseconds;this.countdownTimersetInterval((){this.countdown--;if(this.countdown0){this.clearCountdown();this.isHoldingfalse;this.addLog(运行锁超时自动释放);}},1000);}privateclearCountdown():void{if(this.countdownTimer!-1){clearInterval(this.countdownTimer);this.countdownTimer-1;}}注意这个倒计时是 UI 层面的视觉反馈不是系统行为。系统的运行锁超时由hold(timeout)参数决定超时后系统自动释放锁——应用不需要手动干预。按钮状态机Demo 的操作按钮根据运行锁的当前状态动态变化状态锁对象是否持锁按钮未创建nullfalse[创建运行锁]已创建未持锁RunningLockfalse[持有 Hold] [销毁]已创建持锁中RunningLocktrue[释放 Unhold] [销毁]这构成了一个清晰的三态状态机避免用户执行无效操作。权限配置运行锁需要ohos.permission.RUNNING_LOCK权限。在module.json5中声明requestPermissions:[{name:ohos.permission.RUNNING_LOCK,reason:$string:running_lock_reason,usedScene:{abilities:[EntryAbility],when:inuse}}]同时在resources/base/element/string.json中定义授权原因{name:running_lock_reason,value:需要在后台持续运行以完成文件传输和导航等任务}实际应用场景场景 1导航应用导航是最经典的运行锁场景。用户开车时需要屏幕常亮但不需要持续触摸屏幕// 开始导航时this.navLockawaitrunningLock.create(NavApp.Navigation,runningLock.RunningLockType.BACKGROUND);this.navLock.hold(3600000);// 持锁 1 小时// 导航结束时this.navLock.unhold();场景 2文件传输传输大文件时即使屏幕熄灭了也应该保持后台传输// 开始传输this.transferLockawaitrunningLock.create(FileApp.Transfer,runningLock.RunningLockType.BACKGROUND_USER_IDLE);this.transferLock.hold(600000);// 持锁 10 分钟// 传输完成this.transferLock.unhold();场景 3视频播放视频播放器在后台播放音频时需要持有运行锁// 切换到后台播放this.audioLockawaitrunningLock.create(PlayerApp.Audio,runningLock.RunningLockType.BACKGROUND);this.audioLock.hold(1800000);// 持锁 30 分钟API 层面刷新四种异步模式本文是鸿蒙新特性系列第六篇。截至目前我们已经在 BasicServicesKit 中遇到了四种不同的异步/同步模式模式示例模块特征同步常量batteryInfo, power直接读取属性零开销PromisewifiManager, window.then().catch()链式调用Callbackthermal注册/取消生命周期管理Promise 对象runningLockcreate()返回 Promise后续对返回对象操作第四种模式Promise 创建 同步操作对象是最灵活的组合——创建是异步的需要向系统服务申请资源但创建后对锁的操作hold/unhold/isHolding都是同步的。这种异步创建 同步使用的设计在系统资源管理类 API 中非常普遍文件句柄、数据库连接、音频流……都用这个模式。权限说明API所需权限isSupported()无需权限create()ohos.permission.RUNNING_LOCKhold()ohos.permission.RUNNING_LOCKunhold()ohos.permission.RUNNING_LOCKisHolding()无需权限注意事项不要让锁永远不释放hold()虽然可以持有较长时间但应选择合理的最小超时值。过度使用运行锁会快速消耗电量。页面销毁时必须释放在aboutToDisappear()中调用unhold()防止页面关闭后运行锁继续阻止休眠。check isSupported 再 create在真机上大部分类型都支持但在某些设备如平板可能没有距离传感器上特定类型不可用。BACKGROUND 已废弃API 10 起BACKGROUND被标记为废弃建议迁移到BACKGROUND_USER_IDLEAPI 23。但为了兼容旧设备当前 Demo 仍使用BACKGROUND。模拟器限制在模拟器上create()和hold()可能因权限和系统服务限制而失败——这是正常的。Demo 中的isSupported()查询逻辑可以在模拟器上完整验证。完整代码import{router}fromkit.ArkUI;importrunningLockfromohos.runningLock;import{FontSize,Spacing}from../common/Constants;EntryComponentstruct RunningLockLabPage{StatebgSupported:booleanfalse;StateproximitySupported:booleanfalse;StatebgIdleSupported:booleanfalse;StatelockCreated:booleanfalse;StateisHolding:booleanfalse;StateholdTimeout:number30000;StatetimeoutPicker:number3;Statecountdown:number0;StateeventLogs:EventLog[][];Stateloading:booleantrue;privaterl:runningLock.RunningLock|nullnull;privatecountdownTimer:number-1;aboutToAppear():void{this.checkSupport();}aboutToDisappear():void{this.clearCountdown();this.releaseLock();}privatecheckSupport():void{this.bgSupportedrunningLock.isSupported(runningLock.RunningLockType.BACKGROUND);this.proximitySupportedrunningLock.isSupported(runningLock.RunningLockType.PROXIMITY_SCREEN_CONTROL);this.bgIdleSupportedrunningLock.isSupported(runningLock.RunningLockType.BACKGROUND_USER_IDLE);this.loadingfalse;}privatecreateLock():void{runningLock.create(RunningLockLab,runningLock.RunningLockType.BACKGROUND).then((lock:runningLock.RunningLock){this.rllock;this.lockCreatedtrue;this.addLog(运行锁创建成功);}).catch((err:Error){this.addLog(创建失败: err.message);});}privateholdLock():void{if(this.rlnull){return;}this.rl.hold(this.holdTimeout);this.isHoldingtrue;this.startCountdown(Math.floor(this.holdTimeout/1000));this.addLog(已持有运行锁);}privatereleaseLock():void{if(this.rlnull){return;}this.clearCountdown();this.rl.unhold();this.isHoldingfalse;}// ... 完整代码参见项目源码}总结本文深入讲解了 HarmonyOS NEXT 中ohos.runningLock模块的设计思路和实战应用三种锁类型BACKGROUND防休眠最常用、PROXIMITY_SCREEN_CONTROL智能灭屏通话场景、BACKGROUND_USER_IDLE空闲防休眠新一代。四阶段生命周期创建create异步→ 持有hold同步指定超时→ 释放unhold同步→ 销毁置 null。每个阶段都需要正确的状态管理和错误处理。超时机制hold(timeout)的强制超时设计既保护了用户电量又让你明确思考我需要多长时间的后台运行。权限前置isSupported()无需权限即可查询先检测再创建先声明权限再使用——这是正确的开发顺序。第四种异步模式create()返回 Promise但hold/unhold/isHolding都是同步的——这种异步创建 同步使用的模式在系统资源管理中很普遍。掌握ohos.runningLock你就能在导航、传输、播放、通话等需要后台持续运行的场景中为用户提供流畅不间断的体验——同时遵循正确的生命周期管理不过度消耗电量。