Flet 服务系列:用 Wakelock 让应用在移动端保持屏幕常亮
Flet 服务系列:用 Wakelock 让应用在移动端保持屏幕常亮
本篇技术指南围绕 Flet 官方文档 services/wakelock.md 所定义的 flet.Wakelock 服务展开,介绍如何在纯 Python 的 Flet 应用中控制设备休眠状态,包括 enable、disable、is_enabled 三个异步方法、完整的可运行示例,以及从 Python 控制层到 Flutter 原生插件层的底层调用链。读完本文,你将能够在 Android / iOS / Web 等目标平台上为你的 Flet 应用一键启用或关闭屏幕常亮功能。
Wakelock 是什么
Wakelock(唤醒锁)是移动与桌面平台上的一项系统能力:当应用处于前台且启用了 wakelock 时,设备屏幕不会因无操作而自动熄灭或进入休眠。这在视频播放、计时器、游戏、扫码、演示文稿等需要长时间保持屏幕可见的场景下尤为关键。
在 Flet 中,Wakelock 被实现为一个 Service(服务) 控件。服务控件不渲染任何可见 UI,而是通过异步方法调用设备的系统能力。Wakelock 的 Python 端定义位于 controls/services/wakelock.py,其类注释精炼地概括了它的用途:
"Prevents the device from sleeping while enabled."(启用后阻止设备休眠。)
从类继承关系看,Wakelock 继承自 controls/services/service.py 中的 Service 基类,而 Service 又继承自 BaseControl。Service 基类在 init() 时会把自身注册到当前页面的服务注册表中(context.page._services.register_service(self)),从而获得与页面生命周期一致的管理能力。
Wakelock 的 API:三个异步方法
Wakelock 类的 API 非常精简,只有三个异步方法,全部通过 _invoke_method 桥接到 Flutter 运行时:
| 方法 | 签名 | 作用 |
|---|---|---|
enable |
async def enable(self) |
启用 wakelock,保持设备屏幕常亮("Keeps the device awake") |
disable |
async def disable(self) |
停用 wakelock,允许设备再次休眠("Allows the device to sleep again") |
is_enabled |
async def is_enabled(self) -> bool |
返回当前 wakelock 是否处于启用状态(True / False) |
对应源码如下(wakelock.py):
async def enable(self):
await self._invoke_method("enable")
async def disable(self):
await self._invoke_method("disable")
async def is_enabled(self) -> bool:
return await self._invoke_method("is_enabled")
注意这三个方法都是 async 的,必须在异步上下文中 await 调用。这正是 Flet 1.0 之后推荐的全异步编程模型——你可以在 async def main(page: ft.Page) 入口中直接使用。
完整示例:一个可运行的状态切换应用
官方为 Wakelock 提供了配套的示例应用,位于 examples/services/wakelock/wakelock/main.py,该文件也正是文档页 <CodeExample path="services/wakelock/main.py"> 所引用的代码。下面给出完整实现:
import flet as ft
async def main(page: ft.Page):
wakelock = ft.Wakelock()
status = ft.Text()
async def update_status():
enabled = await wakelock.is_enabled()
status.value = f"Wakelock enabled: {enabled}"
async def enable_lock():
await wakelock.enable()
await update_status()
async def disable_lock():
await wakelock.disable()
await update_status()
await update_status()
page.add(
ft.SafeArea(
content=ft.Column(
controls=[
ft.Column(
[
status,
ft.Row(
[
ft.Button("Enable wakelock", on_click=enable_lock),
ft.Button(
"Disable wakelock", on_click=disable_lock
),
],
wrap=True,
),
],
)
],
),
)
)
if __name__ == "__main__":
ft.run(main)
示例的界面与交互逻辑非常直观:
- 页面启动时先实例化
ft.Wakelock()(无需添加进page.add的可见控件树,服务控件只负责能力调用); - 用一个
ft.Text显示当前状态,初始通过await wakelock.is_enabled()获取并展示; - 点击 "Enable wakelock" 按钮调用
enable()保持屏幕常亮; - 点击 "Disable wakelock" 按钮调用
disable()恢复系统默认休眠策略; - 每次操作后重新读取
is_enabled()刷新状态文本。
由于 enable / disable / is_enabled 均为异步方法,事件回调也必须写成 async 函数,这与按钮 on_click 的异步事件处理模型完全吻合。
底层原理:Python 如何驱动原生 wakelock
Wakelock 的调用链路体现了 Flet 服务架构的典型模式:Python 控制层不直接接触平台 API,而是通过方法桥接让 Flutter 侧执行真正的系统调用。
第一步:Python 侧的 _invoke_method
Wakelock.enable() 等方法的本质是调用基类 base_control.py 中的 _invoke_method。从源码看,该方法要求控件必须已挂载到某个页面(否则抛出 "Control must be added to the page first" 的 RuntimeError),随后通过当前会话发起调用:
return await self.page.session.invoke_method(
self._i, method_name, arguments, timeout
)
也就是说,"enable" / "disable" / "is_enabled" 这三个字符串方法名会随会话消息一起发送给运行在设备/浏览器中的 Flutter 客户端。
第二步:Flutter 侧的方法监听器
在 Flutter 客户端侧,Wakelock 由 services/wakelock.dart 中的 WakelockService 实现。它在 init() 时注册 _invokeMethod 监听器,把收到的字符串方法名映射到开源插件 wakelock_plus 的调用:
Future<dynamic> _invokeMethod(String name, dynamic args) async {
switch (name) {
case "enable":
return WakelockPlus.enable();
case "disable":
return WakelockPlus.disable();
case "is_enabled":
return WakelockPlus.enabled;
default:
throw Exception("Unknown Wakelock method: $name");
}
}
wakelock_plus 是 Flutter 社区广泛使用的跨平台 wakelock 插件,底层分别对接 Android 的 FLAG_KEEP_SCREEN_ON / WakeLock、iOS 的 UIApplication.shared.isIdleTimerDisabled 以及 Web 的 Screen Wake Lock API,因此 Flet 的 Wakelock 在 Android、iOS、Web 等平台均可工作。WakelockService 在 dispose() 时会移除监听器,避免服务销毁后产生悬挂调用。
第三步:返回值回传
is_enabled 在 Dart 侧返回 WakelockPlus.enabled(布尔值),这个值会作为 _invoke_method 的返回结果回传到 Python 端,最终作为 await wakelock.is_enabled() 的结果返回给调用方。由此完成一次完整的"查询-返回"闭环。
运行示例应用
示例项目位于 examples/services/wakelock/wakelock/,其 pyproject.toml 声明了运行所需的依赖:
dependencies = ["flet"]——运行时依赖仅需 flet 本身;- 开发组
dev依赖包含flet-cli、flet-desktop、flet-web,分别用于命令行工具、桌面打包与 Web 运行; - 项目元数据将该示例归类为 "Utility/Wakelock",标记复杂度为
basic,核心特性为 "wakelock toggle"。
可以直接在项目目录中执行:
pip install flet
flet run
或使用 Python 直接启动:
python main.py
需要说明的是:Wakelock 的"阻止休眠"效果主要作用于移动端(Android / iOS)与 Web 浏览器等存在屏幕休眠策略的平台上;在桌面 Linux / macOS / Windows 上,屏幕常亮行为取决于桌面会话的电源管理策略,效果可能因系统而异。示例中的 ft.SafeArea 用于适配 iOS 刘海屏等安全区域,保证控件不被系统状态栏遮挡。
典型应用场景
结合 Flet 生态中常见的异步长任务、媒体播放与计时类应用,Wakelock 服务的典型使用模式包括:
- 视频 / 音频播放器:播放中调用
enable(),暂停或退出时调用disable(),避免观看途中熄屏; - 倒计时 / 计时器应用:如番茄钟、烹饪计时,保持屏幕可见以便随时查看剩余时间;
- 扫码 / 巡检工具:长时间停留在扫码页时防止设备自动锁屏;
- 演示与信息看板:会议演示或数据大屏应用持续保持屏幕常亮。
一个通用实践是:在页面进入需要常亮的视图时 await wakelock.enable(),离开视图或应用进入后台时 await wakelock.disable(),并以 is_enabled() 校验状态、在 UI 上同步展示当前开关状态。
小结
Flet 的 Wakelock 服务以极简的 API 封装了跨平台屏幕常亮能力:Python 侧只需实例化 ft.Wakelock() 并调用三个异步方法,底层经由会话消息桥接到 Flutter 的 WakelockService,最终由 wakelock_plus 插件对接各平台系统 API。官方文档 services/wakelock.md 与可运行示例 main.py 构成了从入门到落地的完整闭环,你可以直接复制示例代码,在几分钟内为 Flet 应用加入屏幕常亮能力。