Flet 服务系列:用 Wakelock 让应用在移动端保持屏幕常亮

原创2026-09-22 10:47:361,426 阅读
文章标签:前端跨平台UI组件桌面应用移动开发Web框架

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 应用加入屏幕常亮能力。

登录后查看全文
flet