更新记录

1.0.0（2026-08-06）

初始版本发布

平台兼容性

uni-app x(5.15)

Sh-KeepAlive 插件使用说明

Android 保活服务插件，支持前台 Service 保活、WorkManager 周期守护、广播监听自动恢复、桌面 AppWidget 组件（4×2 + 2×2）、通知栏自定义布局、权限管理、最近运行应用查询。

平台支持：仅 Android（最低 API 21）

版本：v1.0.0

一、功能概述

二、使用方法

import {
    startKeepAlive,
    stopKeepAlive,
    isKeepAliveRunning,
    // ... 其他 API
} from '@/uni_modules/sh-keepalive'

所有 API 为函数式导出，直接调用即可。

三、快速开始

App 启动自动保活

// #ifdef APP-ANDROID
import {
    startKeepAlive,
    stopKeepAlive,
    isKeepAliveRunning
} from '@/uni_modules/sh-keepalive'

onLaunch(() => {
    if (!isKeepAliveRunning()) {
        startKeepAlive()
    }
})
// #endif

通知配置

import {
    setNotifyStyle,
    setNotifyNormalText,
    setNotifyCustomLeft,
    setNotifyBottomText,
    addNotifyLog,
    refreshNotification
} from '@/uni_modules/sh-keepalive'

// 普通通知样式
setNotifyStyle("normal")
setNotifyNormalText("保活服务", "服务运行中...")
refreshNotification()

// 自定义布局样式
setNotifyStyle("custom")
setNotifyCustomLeft("今日收款(元)", "128.50", "共 5 笔")
setNotifyBottomText("去查看历史")
refreshNotification()

// 添加日志到自定义通知
addNotifyLog("微信支付收款 +100.00", "10:30:25", "#00AA00")
refreshNotification()

桌面组件

import {
    refreshAllWidgets,
    refreshWidgetRect,
    refreshWidgetSquare,
    setWidgetRectConfig,
    setWidgetSquareConfig,
    addWidgetLogRect,
    addWidgetLogSquare,
    onWidgetRectClick,
    onWidgetSquareClick
} from '@/uni_modules/sh-keepalive'

// 配置组件外观
setWidgetRectConfig("收款助手", "", "停止收款", "#FF5252", "今日已收 5 笔")
refreshWidgetRect()

// 添加日志（icon 支持空字符串/网络URL/文件路径/drawable资源名）
addWidgetLogRect("", "微信支付", "收款 +0.02 元", "成功", "#00AA00")
addWidgetLogSquare("", "银行转账", "到账 +500.00 元", "到账", "#4CAF50")
refreshAllWidgets()

// 自定义组件按钮行为
onWidgetRectClick(() => {
    console.log("4x2 组件按钮被点击")
})
onWidgetSquareClick(() => {
    console.log("2x2 组件按钮被点击")
})

// 恢复默认行为（切换保活开关）
onWidgetRectClick(null)

权限管理

import {
    isNotificationEnabled,
    openNotificationSettings,
    isIgnoringBatteryOptimizations,
    requestIgnoreBatteryOptimizations,
    hasUsageStatsPermission,
    openUsageAccessSettings
} from '@/uni_modules/sh-keepalive'

// 检查通知权限
if (!isNotificationEnabled()) {
    openNotificationSettings()
}

// 检查电池优化白名单
if (!isIgnoringBatteryOptimizations()) {
    requestIgnoreBatteryOptimizations()
}

// 检查使用情况访问权限
if (!hasUsageStatsPermission()) {
    openUsageAccessSettings()
}

最近运行应用

import {
    hasUsageStatsPermission,
    openUsageAccessSettings,
    getRecentTasks
} from '@/uni_modules/sh-keepalive'

// 需要 PACKAGE_USAGE_STATS 权限
if (!hasUsageStatsPermission()) {
    openUsageAccessSettings()
} else {
    const tasks = getRecentTasks(10)
    for (let i = 0; i < tasks.length; i++) {
        console.log(tasks[i].appName + " - " + tasks[i].packageName)
    }
}

四、API 参考

保活控制

权限管理

通知设置

桌面组件刷新

组件配置

组件日志

组件回调

应用查询

五、桌面组件交互说明

如何添加桌面组件：在桌面长按 → 选择"添加小部件" → 搜索"自启动助手" → 选择 4×2 或 2×2 尺寸拖到桌面。

六、通知栏交互说明

七、保活架构

┌─────────────────────────────────────┐
│ KeepAliveService (前台 Service)      │
│ - START_STICKY（被杀自动重建）        │
│ - WakeLock（PARTIAL_WAKE_LOCK）      │
│ - MediaSession（音频焦点）            │
│ - 前台常驻通知（普通/自定义布局）      │
├─────────────────────────────────────┤
│ KeepAliveWorker（WorkManager）       │
│ - 每 15 分钟检查 Service 是否存活     │
│ - 存活则无操作，死亡则自动重启         │
├─────────────────────────────────────┤
│ KeepAliveReceiver（广播监听）         │
│ - 网络变化时检查重启                  │
│ - 电源插拔时检查重启                  │
└─────────────────────────────────────┘

八、权限声明

插件自动声明以下权限，无需手动配置：

<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" />

九、依赖说明

插件自动引入以下依赖：

{
    "dependencies": [
        "androidx.work:work-runtime-ktx:2.9.1"
    ]
}

十、注意事项

1. 自定义基座：插件包含 AAR、AndroidManifest、res 资源和远程依赖，首次使用必须打包自定义基座才能正常运行；之后修改 UTS 代码可直接标准基座调试
2. 通知权限：Android 13+ 需要动态申请 POST_NOTIFICATIONS 权限，否则无法显示常驻通知
3. 电池优化：建议引导用户将 App 加入电池优化白名单，否则后台可能被系统限制导致 Service 被杀死
4. 厂商 ROM：小米、华为、OPPO、vivo 等系统有后台限制，建议引导用户在系统设置中放行自启动、后台运行
5. 桌面组件：需要用户在桌面长按手动添加小组件，搜索"自启动助手"即可找到 4×2 和 2×2 两种尺寸
6. 组件图标：addWidgetLog* 的 icon 参数支持以下格式：
   • 空字符串 "" → 显示 App 默认图标
   • 网络 URL "https://..." → 加载网络图片
   • 文件路径 "/sdcard/..." → 加载本地文件
   • 资源名 "ic_launcher" → 加载 drawable 资源
7. 应用查询：getRecentTasks() 需要用户授予使用情况访问权限（PACKAGE_USAGE_STATS），否则返回空列表
8. 回调生命周期：onWidgetRectClick 和 onWidgetSquareClick 设置了 @UTSJS.keepAlive，回调会持续存活，避免频繁重复调用
9. AAR 编译：原生代码以 AAR 形式封装在 libs/ 目录，源码可联系作者获取