更新记录

1.0.2（2026-05-11） 下载此版本

• 鸿蒙（HarmonyOS）平台支持
  • 实现 KeepLiveManager 管理类
  • 注册/注销保活服务
  • 系统定时器支持（带回调释放保护，单位秒）
  • 闹钟任务支持
  • WiFi锁支持
  • 获取运行时长
  • 前后台状态回调（register 时触发）
  • 添加 module.json5 权限配置

1.0.1（2026-05-10） 下载此版本

• 修复 iOS 系统定时器回调被 UTS 释放的问题
  • 在 Swift 端添加 systemTimerCallback 属性保持回调的强引用
  • 避免出现 "callback 回调函数已释放，不能再次执行" 错误

1.0.0（2026-05-10） 下载此版本

• 初始化项目，发布第一个版本

• Android 平台保活功能：

  • 前台服务保持后台运行
  • 静默音频播放保持活跃
  • 屏幕状态监听（亮屏/熄屏）
  • 应用前后台状态监听
  • 通知点击回调处理
  • 电池优化白名单检测和请求
  • 唤醒锁（Wake Lock）支持
  • WiFi锁支持
  • 系统定时器支持
  • 闹钟任务支持
  • 获取运行时长
  • 隐藏最近任务功能
  • 应用启动器支持
  • 系统设置页面跳转

• iOS 平台保活功能：

  • 后台音频播放保持活跃
  • 静默音频生成和播放
  • 屏幕状态监听
  • 应用前后台状态监听
  • 系统定时器支持
  • 后台任务调度（BGTaskScheduler）

平台兼容性

uni-app(5.0)

uni-app x(5.0)

d-keep-live

插件介绍

d-keep-live 是一个基于 uni-app x 的 UTS 原生插件，用于在 Android/iOS/HarmonyOS 平台上保持应用在后台运行，防止被系统杀死。通过后台服务、前台服务、系统广播监听等方式实现长连接保活功能。

功能特性

核心功能

• 应用保活：通过前台服务和后台服务机制保持应用在后台运行
• 通知栏管理：支持自定义通知栏标题、内容、图标、声音等
• 后台监听：实时监听应用前后台切换状态
• 屏幕状态监听：监听设备屏幕亮灭状态
• 通知点击处理：处理用户点击通知栏的事件

高级功能

• 电池优化白名单：请求并检查应用是否在系统电池优化白名单中
• 唤醒锁（Wake Lock）：获取和释放CPU唤醒锁防止设备进入睡眠状态
• WiFi锁：获取和释放WiFi锁保持WiFi连接
• 系统定时器：支持自定义间隔的系统定时器回调
• 闹钟任务：支持延迟执行和循环执行的任务调度
• 应用隐藏：可选择隐藏最近任务列表中的应用
• 应用启动：支持通过包名启动其他应用
• 自启动设置：开启/关闭应用自启动功能（部分厂商rom支持）
• 系统设置跳转：一键跳转到应用详情页、通知设置页等系统设置界面
• 崩溃重启：应用崩溃后自动重启机制（需开启）
• 后台音乐播放：支持在后台播放音乐

平台支持

• Android (minSdkVersion: 21)
• iOS (ios 13)
• HarmonyOS (开发中...)

安装方法

1. 将 uni_modules/d-keep-live 目录复制到您的 uni-app x 项目根目录下
2. 在 HBuilderX 中打开项目，确保插件已被正确识别
3. 在 manifest.json 中检查插件配置（通常无需额外配置）
4. 使用 HBuilderX 编译运行到真机或模拟器进行测试

使用示例

// 导入插件
import { keepLive } from '@/uni_modules/d-keep-live'

// 创建实例
const kl = new keepLive()

// 配置通知栏
kl.setTitle('后台服务运行中')
kl.setContent('保持应用后台运行以维持长连接')
kl.setSmallIcon('icon_notification') // 需要在resources目录下的drawable资源
kl.setChannelId('keep_live_channel')
kl.setChannelName('后台保活服务')

// 注册回调函数
kl.onAddBackgroundCallback((isBackground) => {
  console.log('应用状态:', isBackground ? '后台' : '前台')
})

kl.onAddScrrenListenerCallback((isScreenOn) => {
  console.log('屏幕状态:', isScreenOn ? '亮屏' : '熄屏')
})

kl.onAddNotificationClickListener((data) => {
  console.log('通知被点击:', data)
})

// 启动保活服务
try {
  kl.register()
  console.log('保活服务启动成功')
} catch (e) {
  console.error('保活服务启动失败:', e)
}

// 获取运行时长
console.log('已运行时长(秒):', kl.getLiveTime())

// 停止服务（当不需要时）
// kl.unregister()

API 参考

配置方法

• setTitle(title: string): 设置通知栏标题
• setContent(content: string): 设置通知栏内容
• setSmallIcon(icon: string): 设置通知栏小图标（需在resources/drawable下）
• setLargeIcon(icon: string): 设置通知栏大图标（当前版本需自行处理Bitmap转换）
• setNotifaicationSoundEnable(enable: boolean): 设置通知声音是否启用
• setChannelId(id: string): 设置通知渠道ID
• setChannelName(name: string): 设置通知渠道名称
• setChannelImportance(importance: number): 设置通知渠道重要级别
• setLockscreenVisibility(visibility: number): 设置锁屏通知可见性
• enableVibration(enable: boolean): 设置通知是否震动
• setAutoCancel(autoCancel: boolean): 设置点击通知后是否自动取消
• setNotifationId(id: number): 设置通知ID
• setNotifationMsgGroup(group: string): 设置通知分组
• setNotifationExterData(data: string): 设置通知额外数据
• setBackgroundMusicEnabled(enabled: boolean): 启用/禁用后台音乐播放
• setMusicId(musicId: string): 设置后台音乐ID
• setMusicVol(vol: number): 设置后台音乐音量 (0-1)

控制方法

• register(): 注册并启动保活服务
• unregister(): 注销并停止保活服务
• isRunning(): 检查服务是否正在运行
• restart(): 重启服务（先注销后注册）
• updateNotification(): 更新通知栏内容
• checkAppNotification(): 检查应用通知是否已启用
• goNotificationSetting(): 打开系统通知设置页
• cancelGroupNotifaon(group: string): 取消指定分组的通知
• cancelNotifation(id: number): 取消指定ID的通知

高级控制

• setWakeLock(type: number, tag: string): 获取唤醒锁
• acquire(timeout: number): 获取唤醒锁带超时时间
• releaseAcquire(): 释放唤醒锁
• requestIgnoreBatteryOptimizations(): 请求加入电池优化白名单
• isIgnoringBatteryOptimizations(): 检查是否在电池优化白名单中
• wifilock(): 获取WiFi锁
• wifiunlock(): 释放WiFi锁
• hideRecentTask(hide: boolean): 隐藏/显示最近任务列表
• toBackground(): 将应用送到后台
• doStartApplicationWithPackageName(pkg: string): 启动指定包名的应用
• setAutoStartEnable(enable: boolean): 设置自启动开关
• goAndroidSystemAppSetting(): 打开系统应用设置页
• setCrashRestartUIEnabled(enable: boolean): 启用/禁用崩溃自动重启

定时器功能

• onStartCSystemTimer(interval: number, callback: () => void): 启动系统定时器
• cancelCSystemTimer(): 取消系统定时器
• clearAllCTimer(): 清除所有定时器
• startAleraTask(delay: number, interval: number, callback: () => void): 启动闹钟任务
• cancleAleraTask(): 取消闹钟任务

回调注册

• onAddBackgroundCallback(callback: (res: boolean) => void): 注册后台状态变化回调
• onAddScrrenListenerCallback(callback: (res: boolean) => void): 注册屏幕状态变化回调
• onAddNotificationClickListener(callback: (d: string) => void): 注册通知点击回调
• onOpenNotificationSetting(callback: (res: boolean) => void): 注册打开通知设置页回调
• onAddCrashRestartCallback(callback: () => void): 注册崩溃重启回调

错误码

插件内部错误统一使用 9010001-9010004 范围：

• 9010001: 应用上下文获取失败
• 9010002: 服务注册失败
• 9010003: 通知创建失败
• 9010004: 其他未知错误

注意事项

1. 此插件需要真机测试，模拟器可能无法完全体现后台保活效果
2. Android 9+ 系统对后台服务有更严格限制，建议使用前台服务模式
3. 部分国内定制ROM（如小米、华为、OV等）可能需要在系统设置中手动允许后台运行
4. 使用唤醒锁和WiFi锁会增加功耗，请在不需要时及时释放
5. 通知栏图标需放置在 uni_modules/d-keep-live/utssdk/app-android/resources/drawable 目录下
6. iOS和HarmonyOS版本正在开发中，当前主要功能在Android平台可用

更新日志

请查看项目根目录下的 CHANGELOG.md 文件获取详细更新历史。

许可证

MIT License