Flet ScreenBrightness 服务:在 Python 中控制 Android/iOS 屏幕亮度

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

Flet ScreenBrightness 服务:在 Python 中控制 Android/iOS 屏幕亮度

Flet 的 ScreenBrightness 服务为 Python 开发者提供了一套跨移动端的屏幕亮度控制 API,可分别读取与设置系统亮度和应用亮度、以动画方式平滑过渡亮度、并在系统或应用亮度变化时实时接收事件回调。本文将以官方示例与仓库源码为依据,完整讲解该服务的注册方式、全部方法与事件、Android 权限配置以及其与 Flutter 端 screen_brightness 插件的底层映射关系,帮助你在 Flet 应用中直接落地亮度调节能力。

服务概览:系统亮度与应用亮度

ScreenBrightness(Python 实现)是 Flet 服务体系(Service)中的一个成员,其类文档明确说明:

Provides access to control and observe system and application screen brightness.

它围绕两个概念展开:

  • 系统亮度(System brightness):设备整体的屏幕亮度,修改后对系统全局生效;是否允许修改取决于系统授权。
  • 应用亮度(Application brightness):仅作用于当前应用窗口/Activity 的亮度覆盖值,不影响系统全局设置,可通过 reset_application_screen_brightness() 随时还原为系统亮度。

所有亮度数值均为 float,取值范围 0.0(最暗)到 1.0(最亮)。

支持平台与前置条件

从源码可以明确确认该服务的平台边界:

  • 支持平台:仅 Android 与 iOS。Python 端在 before_update() 中做了硬性校验,Web 或非移动端直接抛异常:
def before_update(self):
    if self.page.web or not self.page.platform.is_mobile():
        raise FletUnsupportedPlatformException(
            f"{self.__class__.__name__} is only supported on Android and iOS."
        )

(见 screen_brightness.py)。在桌面端或浏览器中运行含 ScreenBrightness 的应用,将收到 FletUnsupportedPlatformException。

  • Android 需要写入系统设置的权限。若要修改系统亮度,必须在应用的 pyproject.toml 中声明权限:
[tool.flet.android.permission]
"android.permission.WRITE_SETTINGS" = true

该权限说明同样写在 Python 端类文档中(见 screen_brightness.py)。注意:只读写应用亮度通常无需此权限,但若调用 set_system_screen_brightness() 则必须声明,且系统可能要求用户在系统设置中额外授予"修改系统设置"权限。

快速开始:注册服务

ScreenBrightness 属于 Flet 的服务(Service),使用前必须挂载到页面。其基类 Service 在 init() 中会自动把自身注册到 context.page._services(见 service.py),而页面端通过内部的 ServiceRegistry(page.py)持有这些服务并同步到前端。

官方示例(main.py)中最简单的接入方式如下:

import flet as ft

async def main(page: ft.Page):
    sb = ft.ScreenBrightness()
    page.services.append(sb)   # 关键:将服务注册进页面
    ...

page.services.append(...) 会触发 ServiceRegistry.register_service(),服务随后被下发到客户端创建对应的原生绑定;若不注册,调用服务方法时会出现"Timeout waiting for invoke method listener"之类的错误。

API 详解

ScreenBrightness 的全部能力都通过异步方法暴露(底层走 _invoke_method 通道与 Dart 端通信)。下表汇总了完整方法清单:

方法 作用 参数/返回
get_system_screen_brightness() -> float 获取当前系统亮度 返回 0.0..1.0
can_change_system_screen_brightness() -> bool 应用是否被允许修改系统亮度 返回布尔值
set_system_screen_brightness(brightness) 设置系统亮度 brightness: Number,范围 0.0..1.0
get_application_screen_brightness() -> float 获取当前应用亮度 返回 0.0..1.0
set_application_screen_brightness(brightness) 设置应用亮度 brightness: Number,范围 0.0..1.0
reset_application_screen_brightness() 将应用亮度还原为系统亮度 无参数
is_animate() -> bool 亮度变化是否启用动画(平台相关) 返回布尔值
set_animate(animate: bool) 启用/禁用亮度变化动画 bool
is_auto_reset() -> bool 生命周期变化时是否自动重置亮度 返回布尔值
set_auto_reset(auto_reset: bool) 启用/禁用生命周期变化时自动重置为系统亮度 bool

(完整签名与文档注释见 screen_brightness.py。)

读取亮度

system_brightness = await sb.get_system_screen_brightness()
app_brightness = await sb.get_application_screen_brightness()
can_change_system = await sb.can_change_system_screen_brightness()

can_change_system_screen_brightness() 很有用:它反映当前系统是否授予了"修改系统设置"能力。示例应用中每次刷新信息时都会查询它,用于向用户展示当前可用状态。

设置亮度

await sb.set_application_screen_brightness(0.5)  # 只影响当前应用
await sb.set_system_screen_brightness(0.5)       # 修改系统全局亮度
await sb.reset_application_screen_brightness()   # 恢复为系统亮度

在 Dart 端,set_system_screen_brightness 与 set_application_screen_brightness 会对参数做 parseDouble 解析,缺失或非法时抛出 ArgumentError.notNull("value")(见 screen_brightness.dart),因此传入的数值必须是合法的数字字面量。

动画与自动重置

await sb.set_animate(True)     # 亮度变化时使用平滑动画(平台相关)
await sb.set_auto_reset(True)  # 应用进入后台/生命周期变化时自动还原亮度

这两个开关在移动端体验上很关键:开启动画能让亮度过渡更柔和;开启自动重置可避免应用退出后把设备亮度"卡"在应用设置的值上。

事件监听:实时感知亮度变化

服务提供两个事件处理器,均携带 ScreenBrightnessChangeEvent 事件对象,其唯一字段 brightness: float 表示变化后的新亮度(范围 0.0..1.0):

  • on_system_screen_brightness_change:系统亮度发生变化时触发(例如用户在控制中心手动拖动亮度条)。
  • on_application_screen_brightness_change:应用亮度发生变化时触发。

事件类的定义见 screen_brightness.py:

@dataclass
class ScreenBrightnessChangeEvent(Event["ScreenBrightness"]):
    brightness: float   # The new screen brightness, in range 0.0..1.0.

监听方式与 Flet 其它事件一致:

async def on_system_change(e: ft.ScreenBrightnessChangeEvent):
    print(f"System brightness changed: {e.brightness:.2f}")

async def on_application_change(e: ft.ScreenBrightnessChangeEvent):
    print(f"Application brightness changed: {e.brightness:.2f}")

sb.on_system_screen_brightness_change = on_system_change
sb.on_application_screen_brightness_change = on_application_change

在 Dart 端,事件订阅是按需建立的:只有当 Python 侧注册了对应事件处理器时,客户端才会订阅 Flutter 插件的亮度变化流(StreamSubscription<double>),并在事件到达时通过 triggerEvent("system_screen_brightness_change", {"brightness": value}) 回传;移除处理器后订阅会被自动取消(见 screen_brightness.dart)。这意味着"监听亮度变化"对性能开销是可控的——不用时不订阅,用完即释放。

完整示例:一个可运行的亮度控制面板

官方示例位于 sdk/python/examples/services/screen_brightness/screen_brightness/main.py,它把上述全部 API 组合成了一个完整的交互面板:滑块调节亮度、按钮分别设置应用/系统亮度、开关控制动画与自动重置、文本框实时显示系统与应用亮度值及变化事件。

import flet as ft


async def main(page: ft.Page):
    sb = ft.ScreenBrightness()
    page.services.append(sb)

    info = ft.Text()
    system_change = ft.Text()
    app_change = ft.Text()

    level = ft.Slider(min=0, max=1, divisions=20, value=0.5, label="Brightness")
    animate_switch = ft.Switch(
        label="Animate application changes", value=True, on_change=None
    )
    auto_reset_switch = ft.Switch(
        label="Auto-reset application brightness on lifecycle changes",
        value=True,
        on_change=None,
    )

    async def refresh_info():
        system_brightness = await sb.get_system_screen_brightness()
        app_brightness = await sb.get_application_screen_brightness()
        can_change_system = await sb.can_change_system_screen_brightness()

        animate_switch.value = await sb.is_animate()
        auto_reset_switch.value = await sb.is_auto_reset()

        info.value = (
            f"System: {system_brightness:.2f} | "
            f"Application: {app_brightness:.2f} | "
            f"Can change system: {can_change_system}"
        )

    async def set_application_brightness(_):
        await sb.set_application_screen_brightness(level.value)
        await refresh_info()

    async def set_system_brightness(_):
        await sb.set_system_screen_brightness(level.value)
        await refresh_info()

    async def reset_application_brightness(_):
        await sb.reset_application_screen_brightness()
        await refresh_info()

    async def toggle_animate(e: ft.Event[ft.Switch]):
        await sb.set_animate(e.control.value)
        await refresh_info()

    async def toggle_auto_reset(e: ft.Event[ft.Switch]):
        await sb.set_auto_reset(e.control.value)
        await refresh_info()

    async def on_system_change(e: ft.ScreenBrightnessChangeEvent):
        system_change.value = f"System brightness changed: {e.brightness:.2f}"

    async def on_application_change(e: ft.ScreenBrightnessChangeEvent):
        app_change.value = f"Application brightness changed: {e.brightness:.2f}"

    sb.on_system_screen_brightness_change = on_system_change
    sb.on_application_screen_brightness_change = on_application_change

    await refresh_info()

    animate_switch.on_change = toggle_animate
    auto_reset_switch.on_change = toggle_auto_reset

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Column(
                        [
                            info,
                            level,
                            ft.Row(
                                [
                                    ft.Button(
                                        "Set application",
                                        on_click=set_application_brightness,
                                    ),
                                    ft.Button(
                                        "Set system", on_click=set_system_brightness
                                    ),
                                    ft.TextButton(
                                        "Reset application",
                                        on_click=reset_application_brightness,
                                    ),
                                ],
                                wrap=True,
                            ),
                            animate_switch,
                            auto_reset_switch,
                            ft.Divider(),
                            system_change,
                            app_change,
                        ],
                        spacing=12,
                    )
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

运行该示例后,拖动滑块并点击 "Set application"/"Set system" 即可分别调节两种亮度;"Reset application" 一键还原;两个开关分别控制动画与生命周期自动重置;页面底部的 system_change 与 app_change 文本会随外部或内部亮度变化实时刷新。

底层原理:Python 与 Flutter 的调用链

从仓库源码可以完整还原该服务的端到端工作方式:

  1. Python 侧:ScreenBrightness 继承自 Service(继承自 BaseControl),所有方法通过 self._invoke_method("method_name", {"value": ...}) 向客户端发起调用(见 screen_brightness.py)。

  2. 注册与同步:page.services.append(sb) 将服务实例放入 ServiceRegistry._services 并推送更新(见 page.py);服务在 Python 侧不再被强引用时,unregister_services() 会将其从注册表中移除。

  3. Dart 侧:ScreenBrightnessService(screen_brightness.dart)在 init() 中注册 _invokeMethod 监听器,按方法名把调用转发给 Flutter 社区插件 screen_brightness:

    • get_system_screen_brightness → _screenBrightness.system
    • can_change_system_screen_brightness → _screenBrightness.canChangeSystemBrightness
    • set_system_screen_brightness → _screenBrightness.setSystemScreenBrightness(brightness)
    • get_application_screen_brightness → _screenBrightness.application
    • set_application_screen_brightness → _screenBrightness.setApplicationScreenBrightness(brightness)
    • reset_application_screen_brightness → _screenBrightness.resetApplicationScreenBrightness()
    • is_animate / set_animate / is_auto_reset / set_auto_reset → 插件对应的属性与方法

    若方法名未知,会抛出 Unknown ScreenBrightness method;Web 平台上 _invokeMethod 直接返回 null,且监听器订阅会被 _disposeSubscriptions() 释放(见 screen_brightness.dart)。

  4. 事件回传:Dart 端通过插件的 onSystemScreenBrightnessChanged / onApplicationScreenBrightnessChanged 流监听原生亮度变化,随后 triggerEvent(...) 把 brightness 值送回 Python,由 Python 端分发给用户注册的回调。

注意事项与最佳实践

  • 只在移动端使用:在桌面、Web 环境创建 ScreenBrightness 会在更新阶段抛出 FletUnsupportedPlatformException,代码中应结合平台判断后再创建服务。
  • Android 系统亮度修改需要权限:在 pyproject.toml 中声明 android.permission.WRITE_SETTINGS,并注意部分设备还需用户在系统设置中手动授权;can_change_system_screen_brightness() 可用于检测授权状态。
  • 优先使用应用亮度:如果只是想让应用界面在阅读模式下变暗、退出后恢复原状,使用 set_application_screen_brightness() + set_auto_reset(True) 是最安全、无需系统权限的做法。
  • 事件处理器按需订阅:Dart 端只在注册了回调时才订阅原生亮度流,因此不需要监听变化时不要设置 on_*_change 处理器,以减少不必要的原生资源占用。

相关参考:服务基类实现见 service.py,页面服务注册表见 page.py,ScreenBrightness 与 ScreenBrightnessChangeEvent 的导出见 flet/init.py。

登录后查看全文
flet