Flet Brightness 完全指南：明暗对比度枚举与系统栏亮度控制源码级解析

2026/11/5 1:41:23

Flet Brightness 完全指南：明暗对比度枚举与系统栏亮度控制源码级解析

【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet

当你的应用需要跟随用户的系统深浅色设置切换外观，或者要在自定义颜色的状态栏上保证图标依然清晰可读时，你需要操作的对象就是 Flet 的Brightness枚举。它不控制屏幕亮不亮，而是回答一个更细的问题："当前这块背景是亮的还是暗的？"

最小可运行示例：30 秒跑通 Flet Brightness

下面这个示例覆盖了ft.Brightness的三种典型行为：监听平台明暗切换、读取当前平台模式、设置应用窗口明暗：

import flet as ft def main(page: ft.Page): def on_change(e: ft.PlatformBrightnessChangeEvent): page.window.brightness = e.brightness # 窗口外观跟随系统 page.on_platform_brightness_change = on_change page.add(ft.Text(f"平台当前模式: {page.platform_brightness}")) ft.app(main)

运行后，修改操作系统的明暗设置，窗口外观会随之变化。接下来拆解它背后的机制。

成员与语义边界：Brightness 只描述对比度

Brightness定义在 types.py L882-L901，docstring 原文 "Describes the contrast of a theme or color palette."，即"描述主题或调色板的对比度"。全部成员如下：

成员	字符串值	源码 docstring 原文	语义
`ft.Brightness.LIGHT`	`"light"`	"The color is light and will require a dark text color to achieve readable contrast. For example, the color might be bright white, requiring black text."	底色是亮的，需要配深色文字才可读，例如亮白背景配黑字
`ft.Brightness.DARK`	`"dark"`	"The color is dark and will require a light text color to achieve readable contrast. For example, the color might be dark grey, requiring white text."	底色是暗的，需要配浅色文字才可读，例如深灰背景配白字

划清语义边界：它不是主题切换开关（那是ThemeMode的职责），也不是屏幕物理亮度（那是ScreenBrightness服务的职责，取值是0.0..1.0的浮点数）。它唯一的任务是"底色亮暗 → 前景文字明暗"的推导提示。

易混概念辨析：ThemeMode、Brightness 与 ScreenBrightness

Flet 里有三处名字或职责相近的 API，最容易混。按四个维度对比（源码位置分别为 types.py L860-L879、types.py L882-L901、screen_brightness.py L26-L39）：

维度	`ThemeMode`	`Brightness`	`ScreenBrightness`服务
职责	全局主题模式开关	某处背景的对比度描述	屏幕物理亮度读写
取值域	`SYSTEM`/`LIGHT`/`DARK`	`LIGHT`/`DARK`	`0.0..1.0`连续浮点
生效范围	整个应用	单个组件、系统栏或窗口	整块屏幕
平台限制	跨平台	跨平台	仅 Android 与 iOS（docstring 原文 "Supported platforms: Android, iOS."，即"支持平台：Android、iOS"）

选型口诀：切主题用ThemeMode，标底色用Brightness，调背光用ScreenBrightness。

实战应用地图：Brightness 在 Flet 里的四张落地场景

页面事件：监听平台明暗切换

读现状：Page.platform_brightness（page.py L571-L577），类型Optional[Brightness]，docstring 原文 "The current brightness mode of the host platform."（宿主平台当前的明暗模式），该属性只读。
听变化：Page.on_platform_brightness_change（page.py L614-L619），docstring 原文 "Called when brightness of app host platform has changed."（宿主平台明暗变化时调用）。事件载荷PlatformBrightnessChangeEvent（page.py L277-L289）携带字段brightness: Brightness，即变化后的最新模式。

import flet as ft def main(page: ft.Page): def on_change(e: ft.PlatformBrightnessChangeEvent): name = "暗色" if e.brightness == ft.Brightness.DARK else "亮色" page.window.brightness = e.brightness # 窗口外观随系统走 page.on_platform_brightness_change = on_change ft.app(main)

主题配置：指定状态栏图标明暗

SystemOverlayStyle（theme.py L691-L738）用于定制移动端系统状态栏与导航栏外观，其中三个属性直接吃Brightness：

system_navigation_bar_icon_brightness（L725-L728）：系统导航栏图标明暗
status_bar_brightness（L730-L733）：状态栏明暗
status_bar_icon_brightness（L735-L738）：状态栏图标明暗

Theme通过system_overlay_style（theme.py L3572-L3576，docstring 原文 "Customizes the appearance of the system status bar and navigation bar on mobile platforms."，即定制移动端系统状态栏与导航栏外观）挂载它：

import flet as ft def main(page: ft.Page): page.theme = ft.Theme( system_overlay_style=ft.SystemOverlayStyle( status_bar_color=ft.Colors.WHITE, # 白底状态栏上强制使用深色图标 status_bar_icon_brightness=ft.Brightness.DARK, ) ) ft.app(main)

另外，ChipTheme.brightness（theme.py L1111-L1115）影响所有后代Chip的基准 Material 颜色选择，docstring 原文 "Overrides the default value for all chips which affects various base material color choices in the chip rendering."（覆盖所有 Chip 的默认值，影响 Chip 渲染中各类基础 Material 颜色选择）。

控件属性：推断 CupertinoAppBar 状态栏对比度

CupertinoAppBar.brightness（cupertino_app_bar.py L127-L136）描述所设bgcolor的明暗，docstring 原文 "The brightness of the specifiedbgcolor. Setting this value changes the style of the system status bar."（指定背景色的明暗；设置它会改变系统状态栏样式）。关键默认行为：值为None时，会依据bgcolor的相对亮度自动推断；仅当自动推断结果与预期对比度不符时才手动覆盖：

import flet as ft def main(page: ft.Page): # 蓝色底上强制浅色状态栏内容（默认会自动推断，此处显式声明） page.add(ft.CupertinoAppBar( title=ft.Text("设置"), bgcolor=ft.Colors.BLUE, brightness=ft.Brightness.LIGHT, )) ft.app(main)

输入控件与窗口属性：软键盘和窗口明暗

TextField.keyboard_brightness（textfield.py L614-L619）：设置屏幕软键盘明暗，docstring 原文 "The brightness to use for the onscreen keyboard. This setting is honored on iOS only."（屏幕键盘使用的明暗；该设置仅在 iOS 上生效）。
Window.brightness（window.py L197-L200）：描述应用窗口明暗，docstring 原文 "The brightness of a app window."（应用窗口的明暗），跨桌面平台可用：

import flet as ft def main(page: ft.Page): page.window.brightness = ft.Brightness.DARK # 窗口使用暗色外观 ft.app(main)

常见误区与排错

误区：page.platform_brightness = ft.Brightness.DARK想强制系统变暗。正确做法：该属性只读，切换外观应设置page.window.brightness，或让page.theme_mode = ft.ThemeMode.DARK接管主题。
误区：把ft.Brightness当主题开关，以为设了它就等于切换深色主题。正确做法：ThemeMode决定"用哪套主题"，Brightness只描述"某处底色亮暗"，二者各管各的。
误区：想调屏幕背光却写page.screen_brightness = ft.Brightness.DARK。正确做法：物理亮度必须走page.screen_brightness服务，且入参是0.0..1.0浮点数（事件载荷 docstring 原文 "The new screen brightness, in range0.0..1.0."，即"新的屏幕亮度，范围 0.0 到 1.0"）；在 Android 上改系统亮度还需在pyproject.toml声明android.permission.WRITE_SETTINGS权限（screen_brightness.py L33-L38）。
误区：CupertinoAppBar每次都手动写brightness。正确做法：默认None时会按bgcolor相对亮度自动推断，只在推断结果不满意时覆盖。
误区：给桌面端应用配了keyboard_brightness却看不到效果。正确做法：该属性仅在 iOS 生效，Android 与桌面端忽略此设置。