安卓保活 ios保活 鸿蒙保活 保应用程序稳定后台运行(2025插件大赛二等奖)
插件 ID: 20316
来源: https://ext.dcloud.net.cn/plugin?id=20316
android保活/ios保活/鸿蒙保活 为应用程序提供一个稳定的后台运行环境,为您的应用程序保驾护航,防止程序后台被杀,程序唤醒,息屏唤醒,增加程序活性,优化代码执行,保活稳定
更新记录
1.1.81(2026-05-31)
增加鸿蒙保活,不在只是增加应用优先级,现在是真实的保后台运行
1.1.80(2026-05-21)
优化ios和鸿蒙
1.1.79(2026-05-18)
优化iOS编译报错 查看更多
平台兼容性
uni-app(4.07)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 | | | √ | √ |
- |
- | √ | √ | 5.0 | √ | √ | | | 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 | | |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- |
- | |
uni-app x(4.07)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 | | |
- |
- | 5.0 | √ | √ |
- | |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | | | √ | √ | √ | |
android-keeplive
android-keeplive 是一个用于提升应用后台存活率的保活插件,适用于需要在后台持续维持连接、定时任务、蓝牙通信、推送协同等场景。 支持平台:
- uni-app
- uni-app x
- Android / iOS / Harmony(不同平台能力存在差异,以 Android 能力最完整)
功能概述
- 后台无声音乐保活
- 前台通知常驻保活
- 省电白名单引导
- 通知权限检查与设置页跳转
- 息屏后定时任务
- 唤醒锁
WakeLock - WiFi 锁定
- 通知点击回调
- 前后台状态回调
- 屏幕亮灭状态回调
使用前必读
- Android / iOS 需要使用自定义基座。
- iOS 若用于 uni-app,需要在
manifest.json的后台运行能力中启用audio、fetch。 - Android 端建议提醒用户:
- 锁定最近任务
- 开启自启动
- 允许后台运行
- 关闭省电限制
- Android 默认通知
id为6234542。 - Android 源码版本不包含 aar 源码;其它平台源码包含在插件内。
鸿蒙端额外配置
鸿蒙端如果只是引入插件并调用 keep.register(),但没有补充 harmony-configs 里的 EntryAbility 配置,后台保活不会生效。 请在项目根目录新增或修改 harmony-configs/entry/src/main/module.json5,为 EntryAbility 增加 backgroundModes,并补充 ohos.permission.KEEP_BACKGROUND_RUNNING 权限声明。 如果项目里还没有这个文件,可以先编译一次鸿蒙工程,再从生成的鸿蒙工程中复制 entry/src/main/module.json5 到项目根目录的 harmony-configs/entry/src/main/module.json5 后再修改。 示例配置如下:
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone",
"tablet",
"2in1"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": [
"entity.system.home"
],
"actions": [
"action.system.home"
]
}
],
"backgroundModes": [
"dataTransfer"
]
}
],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET"
},
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
"reason": "$string:EntryAbility_label",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "always"
}
}
]
}
}注意事项:
backgroundModes需要配置在主应用的EntryAbility下,不能只配插件uni_modules/android-keeplive/utssdk/app-harmony/module.json5- 推荐使用
dataTransfer,taskKeeping只在部分设备支持,容易出现9800005 reason里的字符串资源请按你的项目实际情况调整- 修改完
harmony-configs后需要重新编译并重新安装鸿蒙运行包
安装与调试
- 通过插件市场导入到项目。
- 在页面或
App中引入:
// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif- 制作自定义基座。
- 使用自定义基座运行到真机。
- 若手机已安装旧基座,请先卸载后再运行。
重要兼容说明
uni-app x / uvue 页面调用
从当前版本开始,uni-app x / uvue 页面请优先使用插件提供的 Compat 方法;页面层示例不再展示 new UTSCallback(...) 写法:
onOpenNotificationSettingCompatonAddNotificationClickListenerCompatonAddBackgroundCallbackCompatonAddScrrenListenerCallbackCompatstartCSystemTimerCompatonStartCSystemTimerCompat
uni-app 页面调用
uni-app 页面直接传普通 function(...) {} 即可。
快速开始
uni-app x / uvue 示例
// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif
// #ifdef APP
const keep = new KeepLive()
const running = keep.isRunning()
if(running){
console.log("保活正在运行")
return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)
keep.onAddBackgroundCallbackCompat(function(res: boolean) {
console.log('后台运行 ' + res)
})
keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
console.log('屏幕开启状态 ' + res)
})
keep.onAddNotificationClickListenerCompat(function(data: string) {
console.log(data)
})
if (!keep.checkAppNotification()) {
keep.onOpenNotificationSettingCompat(function(res: boolean) {
keep.register()
const ignoring = keep.isIgnoringBatteryOptimizations()
if (!ignoring) {
keep.requestIgnoreBatteryOptimizations()
}
})
} else {
keep.register()
const ignoring = keep.isIgnoringBatteryOptimizations()
if (!ignoring) {
keep.requestIgnoreBatteryOptimizations()
}
}
keep.onStartCSystemTimerCompat(60, function() {
console.log('onStartCSystemTimer')
keep.acquire(1000)
})
// #endifuni-app 示例
// #ifdef APP
import { KeepLive } from '@/uni_modules/android-keeplive'
// #endif
// #ifdef APP
const keep = new KeepLive()
const running = keep.isRunning()
if(running){
console.log("保活正在运行")
return;
}
keep.setTitle('app')
keep.setContent('app is running')
keep.setSmallIcon('icon')
keep.setWakeLock(1, 'keeptag')
keep.setAutoStartEnable(true)
keep.onAddBackgroundCallback(function(res) {
console.log('后台运行 ' + res)
})
keep.onAddScrrenListenerCallback(function(res) {
console.log('屏幕开启状态 ' + res)
})
keep.onAddNotificationClickListener(function(data) {
console.log(data)
})
if (!keep.checkAppNotification()) {
keep.onOpenNotificationSetting(function(res) {
keep.register()
const ignoring = keep.isIgnoringBatteryOptimizations()
if (!ignoring) {
keep.requestIgnoreBatteryOptimizations()
}
})
} else {
keep.register()
const ignoring = keep.isIgnoringBatteryOptimizations()
if (!ignoring) {
keep.requestIgnoreBatteryOptimizations()
}
}
keep.onStartCSystemTimer(60, function() {
console.log('onStartCSystemTimer')
keep.acquire(1000)
})
// #endif与定位插件配合使用
如需后台定位,可配合作者定位插件,在定时器回调中触发定位。 推荐插件:
uni-app x 定位示例
// #ifdef APP
import { isProviderEnabled, onStartLocs, type LocData, type LocationData } from '@/uni_modules/xtf-gpslocation'
// #endif
// #ifdef APP
keep.setBackgroundMusicEnabled(false)
const on = isProviderEnabled()
if (on) {
keep.onStartCSystemTimerCompat(60, function() {
onStartLocs({
backgroud: true,
} as LocData, function(data: LocationData) {
console.log(data)
})
})
}
// #endifuni-app 定位示例
import { isProviderEnabled, onStartLocs } from '@/uni_modules/xtf-gpslocation'
keep.setBackgroundMusicEnabled(false)
const on = isProviderEnabled()
if (on) {
keep.onStartCSystemTimer(60, function() {
onStartLocs({
backgroud: true,
}, function(res) {
console.log(res)
})
})
}常用 API
生命周期
keep.register()
keep.restart()
keep.unregister()
const running = keep.isRunning()通知权限与设置
const on = keep.checkAppNotification()
keep.goNotificationSetting()
keep.requestIgnoreBatteryOptimizations()
const ignoring = keep.isIgnoringBatteryOptimizations()uni-app x / uvue:
keep.onOpenNotificationSettingCompat(function(on: boolean) {
console.log(on)
})uni-app:
keep.onOpenNotificationSetting(function(on) {
console.log(on)
})通知点击回调
uni-app x / uvue:
keep.onAddNotificationClickListenerCompat(function(data: string) {
console.log(data)
})uni-app:
keep.onAddNotificationClickListener(function(data) {
console.log(data)
})前后台与屏幕状态回调
uni-app x / uvue:
keep.onAddBackgroundCallbackCompat(function(res: boolean) {
console.log(res)
})
keep.onAddScrrenListenerCallbackCompat(function(res: boolean) {
console.log(res)
})uni-app:
keep.onAddBackgroundCallback(function(res) {
console.log(res)
})
keep.onAddScrrenListenerCallback(function(res) {
console.log(res)
})定时器
定时器1:系统定时器
uni-app x / uvue:
keep.onStartCSystemTimerCompat(60, function() {
console.log('onStartCSystemTimer')
})uni-app:
keep.onStartCSystemTimer(60, function() {
console.log('onStartCSystemTimer')
})取消:
keep.cancelCSystemTimer()
keep.clearAllCTimer()定时器2:原生闹钟定时器
说明:
- 当前更推荐优先使用“定时器1”
uni-app x / uvue当前没有对应Compat方法时,建议先在插件侧封装后再调用 uni-app x / uvue:
keep.startAleraTask(0, 65 * 1000, function() {
console.log('onAleraTaskListener')
})
keep.cancleAleraTask()uni-app:
keep.startAleraTask(0, 65 * 1000, function() {
console.log('onAleraTaskListener')
})
keep.cancleAleraTask()说明:
startTime:首次执行延迟,毫秒intervalTime:循环时间,毫秒- Android 上推荐大于
60s
定时器3:时钟定时器
说明:
- 当前更推荐优先使用“定时器1”
uni-app x / uvue当前没有对应Compat方法时,建议先在插件侧封装后再调用 uni-app x / uvue:
keep.startKeepClcokTimer(3, function() {
console.log('startKeepClcokTimer')
})
keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()uni-app:
keep.startKeepClcokTimer(3, function() {
console.log('startKeepClcokTimer')
})
keep.cancelKeepClcokTimer()
keep.cancelAllKeepClcokTimer()说明:当前更推荐优先使用“定时器1”。
唤醒锁与 WiFi 锁
keep.setWakeLock(1, 'tag')
keep.acquire(1000)
keep.releaseAcquire()
keep.wifilock()
keep.wifiunlock()通知栏配置
keep.setNotifationId(333)
keep.setChannelId('keeplive')
keep.setChannelName('保活')
keep.setTitle('title')
keep.setContent('content')
keep.setSmallIcon('icon')
keep.setLargeIcon('icon')
keep.setAutoCancel(false)
keep.setNotifaicationSoundEnable(false)
keep.setChannelImportance(3)
keep.setLockscreenVisibility(1)
keep.enableVibration(true)
keep.setAllowBubbles(true)
keep.setShowChannelBrage(true)
keep.setNotifationMsgGroup('group')
keep.setNotifationExterData('data')
keep.setGroupSummary(true)
keep.updateNotification()补充:
- 不同
id会生成不同通知 - 相同
id会更新已有通知 - Android 通知
channel首次创建后不可修改,修改配置请更换新的channelId
通知取消
keep.cancelNotifation(333)
keep.cancelGroupNotifaon('group')
keep.closeNotifation()其它能力
keep.toBackground()
keep.hideRecentTask(true)
keep.goAndroidSystemAppSetting()
keep.setCrashRestartUIEnabled(true)
keep.doStartApplicationWithPackageName('com.test')
keep.restartThisApp()
keep.startAutoStart()
keep.startHighBattery()
const liveTime = keep.getLiveTime()
const liveText = keep.getLiveStr()
const notifationId = keep.getNotifationId()
const pkgName = keep.getPkgName()后台音乐相关
keep.setBackgroundMusicEnabled(true)
keep.setMusicVol(0)
keep.setMusicId('music')
keep.setMusicInterval(6000)说明:
setMusicId('music')对应资源文件为res/raw/music.mp3- 音量范围通常为
0 ~ 1
完整方法清单
以下表格按当前插件实现整理。 平台标记说明:
A= AndroidI= iOSH= Harmony 说明:- 表中“支持平台”表示该方法在对应平台存在实现或兼容占位,不代表每个平台效果完全一致
Compat方法主要给uni-app x / uvue页面使用,用来避免页面层直接处理UTSCallback- 表格中的
uni-app x示例只保留uni-app x一种写法;如果当前方法没有对应Compat,会明确标注“建议先封装 Compat” - 示例统一写成最短调用形式,实际项目中请结合
#ifdef APP、权限判断、异常处理一起使用
权限与系统设置
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | isHavePermision | 检查某个系统权限当前是否已授权。 | A / I / H | pername: string | keep.isHavePermision('android.permission.POST_NOTIFICATIONS') | | | requestPermison | 请求单个系统权限,结果通过回调返回。 | A / I / H | pername: string, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requestPermison('permission', function(res){}) | | | requesMoretPermison | 一次性请求多个系统权限。 | A / I / H | pername: string[], callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requesMoretPermison(['p1', 'p2'], function(res){}) | | | checkAppNotification | 检查应用通知是否处于可用状态。 | A / I / H | 无 | const on = keep.checkAppNotification() | | | checkNotificationPer | 检查通知权限状态,主要兼容 Android 13+。 | A / I / H | 无 | const on = keep.checkNotificationPer() | | | goNotificationSetting | 打开系统通知设置页。 | A / I / H | 无 | keep.goNotificationSetting() | | | requestNotifationPer | 请求通知权限并通过回调返回结果。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.requestNotifationPer(function(res){}) | | | onOpenNotificationSetting | 打开通知设置并在返回后通知当前状态。 | A / I / H | callback: (on:boolean)=>void | uni-app x: keep.onOpenNotificationSettingCompat(function(on: boolean){})uni-app: keep.onOpenNotificationSetting(function(on){}) | | | onOpenNotificationSettingCompat | uvue 页面友好的通知设置回调写法。 | A / I | callback: (on:boolean)=>void | keep.onOpenNotificationSettingCompat(function(on:boolean){}) | | | isIgnoringBatteryOptimizations | 判断应用是否已加入省电白名单。 | A / I / H | 无 | const ignoring = keep.isIgnoringBatteryOptimizations() | | | requestIgnoreBatteryOptimizations | 请求系统将应用加入省电白名单。 | A / I / H | 无 | keep.requestIgnoreBatteryOptimizations() | | | onRequestIgnoreBatteryOptimizations | 监听白名单授权页返回后的结果。 | A / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onRequestIgnoreBatteryOptimizations(function(on){}) | | | goKeepLiveSetting | 跳转到厂商保活或后台运行相关设置页。 | A / I / H | 无 | keep.goKeepLiveSetting() | | | goAndroidSystemAppSetting | 打开当前应用的系统详情设置页。 | A / I / H | 无 | keep.goAndroidSystemAppSetting() | | | startAutoStart | 打开系统自启动管理页。 | A | 无 | keep.startAutoStart() | | | startHighBattery | 打开高耗电或省电限制管理页。 | A | 无 | keep.startHighBattery() | | | getPkgName | 获取当前应用包名。 | A / H | 无 | const pkg = keep.getPkgName() | |
生命周期与运行状态
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | register | 启动保活主逻辑。 | A / I / H | 无 | keep.register() | | | unregister | 停止保活逻辑并清理相关状态。 | A / I / H | 无 | keep.unregister() | | | restart | 重新启动保活流程。 | A / I | 无 | keep.restart() | | | isRunning | 查询当前保活是否正在运行。 | A / I / H | 无 | const running = keep.isRunning() | | | restartThisApp | 重新拉起当前应用。 | A / I / H | 无 | keep.restartThisApp() | | | toBackground | 主动将应用切到后台。 | A / I / H | 无 | keep.toBackground() | | | doStartApplicationWithPackageName | 通过包名启动指定应用。 | A / I / H | packagename: string | keep.doStartApplicationWithPackageName('com.test') | |
通知与通道配置
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | setTitle | 设置通知标题。 | A / I / H | title: string | keep.setTitle('保活中') | | | setContent | 设置通知正文内容。 | A / I / H | content: string | keep.setContent('应用正在运行') | | | setSmallIcon | 设置通知小图标资源名。 | A / I / H | icon: string | keep.setSmallIcon('icon') | | | setLargeIcon | 设置通知大图标资源名。 | A / I / H | icon: string | keep.setLargeIcon('icon') | | | setNotifationId | 设置通知 id,用于更新或区分通知。 | A / I / H | id: number | keep.setNotifationId(333) | | | getNotifationId | 获取当前通知 id。 | A / I / H | 无 | const id = keep.getNotifationId() | | | setChannelId | 设置通知通道 id。 | A / I / H | id: string | keep.setChannelId('keeplive') | | | setChannelName | 设置通知通道名称。 | A / I / H | title: string | keep.setChannelName('保活') | | | setChannelImportance | 设置通知重要级别。 | A / I / H | im: number | keep.setChannelImportance(3) | | | setLockscreenVisibility | 设置通知在锁屏界面的可见性。 | A | b: number | keep.setLockscreenVisibility(1) | | | setAllowBubbles | 设置通知是否允许气泡展示。 | A | b: boolean | keep.setAllowBubbles(true) | | | enableVibration | 设置通知是否启用震动��� | A | b: boolean | keep.enableVibration(true) | | | setNotifaicationSoundEnable | 设置通知是否播放声音。 | A / I / H | on: boolean | keep.setNotifaicationSoundEnable(false) | | | setShowChannelBrage | 设置通知角标显示开关。 | A | on: boolean | keep.setShowChannelBrage(true) | | | setAutoCancel | 设置点击通知后是否自动取消。 | A | b: boolean | keep.setAutoCancel(false) | | | setNotifationMsgGroup | 设置通知所属分组名称。 | A | group: string | keep.setNotifationMsgGroup('group1') | | | setNotifationExterData | 设置通知附加透传数据。 | A | group: string | keep.setNotifationExterData('extra') | | | setGroupSummary | 设置通知是否为分组摘要。 | A | hide: boolean | keep.setGroupSummary(true) | | | preCreateNotificationChannel | 提前创建通知通道。 | A / I / H | 无 | keep.preCreateNotificationChannel() | | | updateNotification | 按当前配置刷新通知。 | A / I / H | 无 | keep.updateNotification() | | | hideNotification | 控制通知隐藏状态,不建议常用。 | A / I / H | hide: boolean | keep.hideNotification(false) | | | cancelNotifation | 取消指定 id 的通知。 | A / I / H | id: number | keep.cancelNotifation(333) | | | cancelGroupNotifaon | 取消某个分组下的通知。 | A | group: string | keep.cancelGroupNotifaon('group1') | | | closeNotifation | 关闭当前保活通知。 | A / I / H | 无 | keep.closeNotifation() | | | setNotifationAcIntent | 设置通知点击后回到当前页面。 | A / I / H | 无 | keep.setNotifationAcIntent() | | | setNotifationBrodcastIntent | 设置通知点击广播行为。 | A / I / H | 无 | keep.setNotifationBrodcastIntent() | | | setNewPendingIntent | 预留给新的通知点击意图逻辑。 | A | 无 | keep.setNewPendingIntent() | |
通知、前后台、屏幕回调
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | onAddNotificationClickListener | 监听用户点击通知后的回调。 | A / I / H | callback | uni-app x: keep.onAddNotificationClickListenerCompat(function(data: string){})uni-app: keep.onAddNotificationClickListener(function(data){}) | | | onAddNotificationClickListenerCompat | uvue 页面友好的通知点击回调写法。 | A / I | callback: (d:string)=>void | keep.onAddNotificationClickListenerCompat(function(data:string){}) | | | onAddBackgroundCallback | 监听应用前后台切换状态。 | A / I / H | callback | uni-app x: keep.onAddBackgroundCallbackCompat(function(on: boolean){})uni-app: keep.onAddBackgroundCallback(function(on){}) | | | onAddBackgroundCallbackCompat | uvue 页面友好的前后台状态回调。 | A / I | callback: (sth:boolean)=>void | keep.onAddBackgroundCallbackCompat(function(on:boolean){}) | | | onAddScrrenListenerCallback | 监听屏幕亮屏或息屏状态变化。 | A / I / H | callback | uni-app x: keep.onAddScrrenListenerCallbackCompat(function(on: boolean){})uni-app: keep.onAddScrrenListenerCallback(function(on){}) | | | onAddScrrenListenerCallbackCompat | uvue 页面友好的屏幕状态回调。 | A / I | callback: (sth:boolean)=>void | keep.onAddScrrenListenerCallbackCompat(function(on:boolean){}) | | | checkAppNotifationPer | 以数值形式返回通知权限状态。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.checkAppNotifationPer(function(res){}) | |
定时器与线程
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | startCSystemTimer | 启动系统定时器,适合周期性后台任务。 | A / I / H | time: number, callback: ()=>void | uni-app x: keep.startCSystemTimerCompat(60, function(){})uni-app: keep.startCSystemTimer(60, function(){}) | | | startCSystemTimerCompat | uvue 页面友好的系统定时器。 | A / I / H | time: number, callback: ()=>void | keep.startCSystemTimerCompat(60, function(){}) | | | onStartCSystemTimer | 启动系统定时器的保留命名版本。 | A / I / H | time: number, callback: ()=>void | uni-app x: keep.onStartCSystemTimerCompat(60, function(){})uni-app: keep.onStartCSystemTimer(60, function(){}) | | | onStartCSystemTimerCompat | uvue 页面友好的保留命名系统定时器。 | A / I / H | time: number, callback: ()=>void | keep.onStartCSystemTimerCompat(60, function(){}) | | | startAleraTask | 启动原生闹钟定时器,适合长周期任务。 | A / I / H | startTime: number, intervalTime: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.startAleraTask(0, 65000, function(){}) | | | cancleAleraTask | 取消原生闹钟定时器。 | A / I | 无 | keep.cancleAleraTask() | | | startKeepClcokTimer | 启动时钟定时器。 | A / I / H | time: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.startKeepClcokTimer(3, function(){}) | | | cancelKeepClcokTimer | 取消当前时钟定时器。 | A / I / H | 无 | keep.cancelKeepClcokTimer() | | | cancelAllKeepClcokTimer | 取消所有时钟定时器。 | A / I / H | 无 | keep.cancelAllKeepClcokTimer() | | | cancelCSystemTimer | 取消系统定时器。 | A / I / H | 无 | keep.cancelCSystemTimer() | | | clearAllCTimer | 清理全部系统定时器。 | A / I / H | 无 | keep.clearAllCTimer() | | | onStartWorkerTimer | 启动 worker 定时器。 | A | time: number, callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onStartWorkerTimer(10, function(){}) | | | cancelWorker | 取消 worker 定时器。 | A | 无 | keep.cancelWorker() | | | setWorkerEnabled | 开关 worker 能力。 | A / I / H | on: boolean | keep.setWorkerEnabled(true) | | | onExecThreadTask | 在线程池中执行一段任务。 | A / I / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onExecThreadTask(function(){}) | | | onExecMainTask | 在主线程中执行一段任务。 | A / H | callback | uni-app x: 建议先在插件侧封装 Compatuni-app: keep.onExecMainTask(function(){}) | | | setWorkOnMainThread | 设置内部逻辑是否在主线程执行。 | A / I / H | t: boolean | keep.setWorkOnMainThread(true) | |
唤醒锁、后台音乐与保活辅助
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | setWakeLock | 配置 WakeLock 类型和标识。 | A / I | state: number, tag: string | keep.setWakeLock(1, 'tag') | | | acquire | 获取唤醒锁,保持 CPU 唤醒。 | A / I | time: number | keep.acquire(1000) | | | releaseAcquire | 释放当前唤醒锁。 | A / I | 无 | keep.releaseAcquire() | | | wifilock | 锁定 WiFi,避免网络休眠。 | A / I / H | 无 | keep.wifilock() | | | wifiunlock | 释放 WiFi 锁。 | A / I / H | 无 | keep.wifiunlock() | | | setBackgroundMusicEnabled | 设置后台无声音乐保活开关。 | A / I / H | on: boolean | keep.setBackgroundMusicEnabled(true) | | | setMusicEnabled | 设置音乐功能总开关。 | A / I / H | en: boolean | keep.setMusicEnabled(true) | | | setMusicId | 设置后台播放的音频资源名。 | A / I / H | musicId: string | keep.setMusicId('music') | | | setMusicVol | 设置后台音乐音量。 | A / I / H | vol: number | keep.setMusicVol(0) | | | setMusicInterval | 设置后台音乐循环或播放间隔。 | A / I / H | t: number | keep.setMusicInterval(6000) | | | hideRecentTask | 控制最近任务卡片是否隐藏。 | A / I | hide: boolean | keep.hideRecentTask(true) | | | setAutoStartEnable | 标记或配置自启动相关状态。 | A / I / H | en: boolean | keep.setAutoStartEnable(true) | |
状态查询与调试辅助
| 方法名 | 方法介绍 | 支持平台 | 参数 | 示例 | | | getLiveTime | 获取保活运行时长,单位毫秒。 | A / I / H | 无 | const liveTime = keep.getLiveTime() | | | getLiveStr | 获取格式化后的保活运行时长文本。 | A / I / H | 无 | const liveStr = keep.getLiveStr() | | | setDebug | 打开或关闭调试模式。 | A / I / H | d: boolean | keep.setDebug(true) | | | setCrashRestartUIEnabled | 设置崩溃后是否自动恢复界面。 | A / I / H | hide: boolean | keep.setCrashRestartUIEnabled(true) | | | crash | 主动触发崩溃,通常只用于调试。 | A / H | 无 | keep.crash() | | | startMicSevice | 预留的麦克风服务入口。 | A / I / H | 无 | keep.startMicSevice() | |
图标与资源放置
uni-app x uni-app
Android 小图标资源放在:
uni_modules/android-keeplive/utssdk/app-android/resAndroid 小图标资源放在插件 Android 原生 drawable 资源目录,图标名称通过setSmallIcon('icon')传入。
常见问题
1. UTSCallback 在 uvue 页面里标红
原因通常是 HBuilderX 页面编辑器的语法服务对 UTSCallback 识别不完整,不代表编译失败。 建议:
- 在
uvue页面中优先使用本文档里的Compat方法 - 页面层统一直接写普通
function(...) {}回调
3. 标准基座运行无效
本插件依赖原生能力,运行到标准基座时相关能力可能不生效,请使用自定义基座。
注意事项
- Android 平台能力最完整
- iOS / Harmony 部分接口仅做兼容保留,不一定具备与 Android 相同的原生效果
- 息屏保活、后台执行、通知常驻等行为会受到 ROM、系统版本、厂商限制影响
- 对于高频后台任务,请结合用户系统设置、自启动、忽略电池优化等方式一起使用