Flet ScreenBrightness 服务:在 Python 中控制 Android/iOS 屏幕亮度
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 的调用链
从仓库源码可以完整还原该服务的端到端工作方式:
-
Python 侧:
ScreenBrightness继承自Service(继承自BaseControl),所有方法通过self._invoke_method("method_name", {"value": ...})向客户端发起调用(见 screen_brightness.py)。 -
注册与同步:
page.services.append(sb)将服务实例放入ServiceRegistry._services并推送更新(见 page.py);服务在 Python 侧不再被强引用时,unregister_services()会将其从注册表中移除。 -
Dart 侧:
ScreenBrightnessService(screen_brightness.dart)在init()中注册_invokeMethod监听器,按方法名把调用转发给 Flutter 社区插件screen_brightness:get_system_screen_brightness→_screenBrightness.systemcan_change_system_screen_brightness→_screenBrightness.canChangeSystemBrightnessset_system_screen_brightness→_screenBrightness.setSystemScreenBrightness(brightness)get_application_screen_brightness→_screenBrightness.applicationset_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)。 -
事件回传: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。