WakeLock 扩展

WakeLock 扩展

WakeLock 是一个免费的设备唤醒管理扩展，用于防止应用程序被操作系统自动关闭。该扩展提供了 WakeLock、WifiLock 和电池优化管理功能，确保应用能够在后台长时间运行，防止设备进入省电模式。

包名：de.UllisRoboterSeite.UrsAI2WakeLock

版本：1.7

发布日期：2021年7月20日

作者：Ulli’s Roboter Seite

文件大小：13.8 KB

与 KeepAlive 扩展的区别

WakeLock 和 KeepAlive 都是用于防止应用被系统关闭的扩展，但有以下主要区别：

特性	WakeLock	KeepAlive
包名	`de.UllisRoboterSeite.UrsAI2WakeLock`	`de.ullisroboterseite.ursai2keepawake`
版本	1.7 (2021年)	1.1 (2024年)
前台服务	❌ 不支持	✅ 核心功能
通知系统	❌ 无通知功能	✅ 完整的通知和通知通道管理
复杂度	🔸 简单基础	🔸🔸 功能丰富
电池消耗	🔸 相对较少	🔸🔸 较高（前台服务+通知）
用户体验	静默运行，用户无感知	通过通知明确告知用户后台状态
适用场景	简单唤醒锁需求	复杂后台任务，需要用户交互
扩展集成	独立运行	支持 UrsNotification、UrsIntent 等扩展集成

选择建议：

选择 WakeLock：需要简单的唤醒锁功能，不需要用户通知，对电池消耗敏感
选择 KeepAlive：需要长时间后台运行，需要用户知道应用状态，需要通知交互

下载链接

扩展文件：

de.UllisRoboterSeite.UrsAI2WakeLock.aix

示例文件：

UrsWakeLockTest.aia

功能概述

扩展特性

CPU 唤醒锁：防止 CPU 被系统关闭
WiFi 唤醒锁：保持 WiFi 连接不断开
屏幕唤醒锁：防止屏幕变暗
电池优化管理：请求忽略电池优化
多种锁类型：支持完整的、部分的不同唤醒锁
后台运行：确保应用在后台长时间运行
定时任务支持：配合定时器执行后台任务

版本历史

1.0 (2020-03-07)：初始版本
1.1 (2020-07-16)：添加电池优化相关方法
1.2 (2020-08-05)：修复 Release() 方法无效问题
1.3 (2020-08-08)：修复多次调用 Release 导致的异常
1.4 (2021-01-26)：添加 WifiLock 功能
1.5 (2021-03-21)：添加版本属性和 SDK 版本检查
1.7 (2021-07-20)：添加 OnAfterRelease、AcquireCausesWakeup 属性和相关方法

截图

权限请求示例

权限请求

应用截图

使用场景

三种主要使用场景：

定时任务：在特定时间（或周期性）执行某些操作，例如记录和保存测量数据
事件响应：应用需要响应外部事件，例如响应传入的 MQTT 消息
屏幕常亮：防止屏幕变暗，例如在显示食谱时

函数

AquireFullWakeLock 获取完整唤醒锁()

获取完整的唤醒锁，保持设备完全唤醒，包括 CPU 和屏幕。

返回类型：无返回值

AquirePartialWakeLock 获取部分唤醒锁()

获取部分唤醒锁，仅保持 CPU 运行，允许屏幕关闭。

返回类型：无返回值

AquireScreenBrightWakeLock 获取屏幕明亮唤醒锁()

获取屏幕明亮唤醒锁，保持屏幕亮着且亮度不变。

返回类型：无返回值

AquireScreenDimWakeLock 获取屏幕昏暗唤醒锁()

获取屏幕昏暗唤醒锁，保持屏幕亮着但允许变暗。

返回类型：无返回值

AquireWifiLock 获取WiFi锁()

获取 WiFi 锁，保持 WiFi 连接不断开。

返回类型：无返回值

Release 释放()

释放当前持有的所有唤醒锁。

返回类型：无返回值

ReleaseWifiLock 释放WiFi锁()

释放当前持有的 WiFi 锁。

返回类型：无返回值

RequestIgnoreBatteryOptimization 请求忽略电池优化()

请求系统忽略应用的电池优化设置。

返回类型：无返回值

OpenBatteryOptimizationSettings 打开电池优化设置()

打开系统电池优化设置页面，让用户手动配置。

返回类型：无返回值

EnableShowOnLockScreen 启用锁屏显示(启用)

启用或禁用在锁屏界面上显示。

启用：布尔类型，是否启用锁屏显示
返回类型：无返回值

属性

IsHold 是否持有锁

获取当前是否持有唤醒锁。

类型：布尔类型
只读：是

IsWifiLockHeld 是否持有WiFi锁

获取当前是否持有 WiFi 锁。

类型：布尔类型
只读：是

IsIgnoringBatteryOptimizations 是否忽略电池优化

获取应用是否被设置为忽略电池优化。

类型：布尔类型
只读：是

Version 版本

获取扩展的版本信息。

类型：文本类型
只读：是

VersionSDK SDK版本

获取扩展支持的 SDK 版本。

类型：文本类型
只读：是

AcquireCausesWakeup 获取时唤醒设备

获取或设置获取唤醒锁时是否唤醒设备。

类型：布尔类型
默认值：false

OnAfterRelease 释放后执行

获取或设置释放唤醒锁后要执行的动作。

类型：文本类型
默认值：空

应用场景

1. 数据记录应用

定期记录传感器数据：

当 Clock1.计时器
    调用 WakeLock1.AquirePartialWakeLock 获取部分唤醒锁
    调用 读取传感器数据
    调用 保存数据到文件
    调用 WakeLock1.Release 释放

2. MQTT 客户端

保持 MQTT 连接活跃：

当 应用启动
    调用 WakeLock1.AquireWifiLock 获取WiFi锁
    调用 WakeLock1.AquirePartialWakeLock 获取部分唤醒锁

当 应用关闭
    调用 WakeLock1.ReleaseWifiLock 释放WiFi锁
    调用 WakeLock1.Release 释放

3. 食谱显示应用

保持屏幕常亮：

当 显示食谱页面
    调用 WakeLock1.AquireScreenBrightWakeLock 获取屏幕明亮唤醒锁

当 离开食谱页面
    调用 WakeLock1.Release 释放

4. 长时间运行的应用

配置电池优化：

当 应用启动
    如果 WakeLock1.IsIgnoringBatteryOptimizations = false 则
        调用 WakeLock1.RequestIgnoreBatteryOptimization 请求忽略电池优化
        显示通知 "请在设置中允许忽略电池优化"

5. 下载管理器

确保下载完成：

当 开始下载
    调用 WakeLock1.AquireWifiLock 获取WiFi锁
    调用 WakeLock1.AquirePartialWakeLock 获取部分唤醒锁

当 下载完成
    调用 WakeLock1.Release 释放

重要说明

权限要求

扩展需要 WAKE_LOCK 权限才能正常工作。

Companion 限制

注意：该扩展在 AI2 Companion 中无法正常工作，因为 Companion 缺少 WAKE_LOCK 权限。可能的解决方案是修补 AI2 Companion 以添加额外权限。

电池优化

从 Android 6.0 (Marshmallow) 开始，系统引入了 Doze 模式来优化电池寿命。如果没有任何应用被主动使用，该功能会逐渐关闭所有功能（显示、CPU、WiFi 等）。WakeLock 功能也被部分禁用。

最佳实践

及时释放：使用完唤醒锁后及时释放，避免过度消耗电池
最小化使用：只使用必要的唤醒锁类型
错误处理：处理权限请求失败的情况
用户提示：告知用户为什么需要这些权限

技术说明

Android 系统限制

Doze 模式：Android 6.0+ 的省电模式
应用待机：长时间未使用的应用会被置于待机状态
电池优化：系统会自动优化应用的后台活动

唤醒锁类型

PARTIAL_WAKE_LOCK：保持 CPU 运行，屏幕可以关闭
SCREEN_DIM_WAKE_LOCK：保持屏幕亮着但允许变暗
SCREEN_BRIGHT_WAKE_LOCK：保持屏幕亮着且亮度不变
FULL_WAKE_LOCK：保持 CPU 和屏幕都处于活跃状态

常见问题

Q: 为什么在 Companion 中无法使用？

A: Companion 缺少必要的 WAKE_LOCK 权限，需要在编译的应用中使用。

Q: 如何处理电池优化？

A: 使用 RequestIgnoreBatteryOptimization 方法请求忽略电池优化，或引导用户手动设置。

Q: 使用唤醒锁会大量消耗电池吗？

A: 是的，特别是完整唤醒锁。建议使用最小必要的锁类型并及时释放。

Q: WiFi 锁有什么作用？

A: 防止系统关闭 WiFi，保持网络连接稳定。

Q: 应用被系统杀死怎么办？

A: 配置电池优化设置，使用适当的唤醒锁，避免长时间后台运行。

版权信息

本文档基于 Ulli’s Roboter Seite 网站页面整理，原作者为 Ulli。

原始链接：https://ullisroboterseite.de/android-AI2-WakeLock-en.html

文档翻译和整理：AI2中文网

最后更新：2024年12月16日

WakeLock 扩展：保持设备唤醒扩展，防止系统休眠和电池优化