Flet DividerTheme 分割线主题配置指南：统一控制 Divider 与 VerticalDivider 的视觉属性

• 前端
• 跨平台
• 桌面应用
• 移动开发

DividerTheme是 Flet 主题体系（ft.Theme）中用于统一定义分割线视觉属性的值类型，它同时作用于Divider、VerticalDivider、ListTile之间的分隔线以及DataTable行间的分隔线。读完本文，你将掌握DividerTheme全部 5 个属性（颜色、线宽、占据空间、两端缩进）的含义与默认值，理解它与Divider/VerticalDivider控件属性之间的优先级关系，并能通过page.theme或ft.app(theme=...)为整个应用一键定制分割线外观。

DividerTheme 是什么

在 Flet 中，分割线控件有横向的ft.Divider和纵向的ft.VerticalDivider，此外 Material 组件中的ListTile之间、DataTable行之间也会绘制分割线。如果逐个控件去设置颜色、粗细，既繁琐又难以保持一致。

DividerTheme正是为此而生的统一配置入口。其类定义位于 sdk/python/packages/flet/src/flet/controls/theme.py：

@value class DividerTheme: """ Defines the visual properties of Divider, VerticalDivider, dividers between ListTiles, and dividers between rows in DataTable. """ color: Optional[ColorValue] = None thickness: Optional[Number] = None space: Optional[Number] = None leading_indent: Optional[Number] = None trailing_indent: Optional[Number] = None

从类文档字符串可以确认，它的作用范围包括四类分割线：

• flet.Divider（横向分割线）
• flet.VerticalDivider（纵向分割线）
• ListTile之间的分隔线
• DataTable行之间的分隔线

DividerTheme本身是一个纯值类型（非控件），通过@value装饰器实现为 dataclass 并启用属性变更追踪（详见下文"源码实现"一节），因此可以被安全地放入Theme对象参与整树主题传播。

五个属性逐一详解

DividerTheme的属性不多，但每个都对应分割线渲染的一个关键维度。以下含义均来自 theme.py 中的属性文档。

color：分割线颜色

color: Optional[ColorValue] = None

分割线（Divider与VerticalDivider）绘制时使用的颜色，同样作用于ListTile之间、DataTable行间的分割线。

color接受任意ColorValue，即既可以是ft.Colors中的命名颜色，也可以是十六进制字符串（如"#E0E0E0"）或ft.Colors.with_opacity()等构造的带透明度颜色。值为None时表示不覆盖，交由控件自身的color属性或 Flutter 侧默认值决定。

thickness：分割线线宽

thickness: Optional[Number] = None

分割线内部实际绘制线条的粗细。注意它和"分割线占据的空间"是两个概念：thickness只决定那根线的粗细，而分割线整体占用的布局空间由space（见下）控制。

结合 Divider 控件源码 可知：thickness为0.0时，分割线始终绘制为恰好一个设备像素（one device pixel）高的细线，这是 Material 规范中"hairline"分割线的实现方式。

space：分割线占据的空间

space: Optional[Number] = None

对于横向的Divider，space表示其高度；对于纵向的VerticalDivider，space表示其宽度。即分割线在布局中占用的水平或垂直空间大小。

当控件自身的height（Divider）或width（VerticalDivider）未设置时，会回退到该值；若该值也为None，则默认取16.0（见 divider.py 与 vertical_divider.py 的文档说明）。

leading_indent：前缘空白

leading_indent: Optional[Number] = None

Divider前缘（leading edge，即水平方向起始侧）或VerticalDivider顶部（top edge）的空白空间大小。实际渲染时，分割线以space规定的区域居中，线两侧再按leading_indent/trailing_indent留出空白，从而形成"左右/上下留白、中间画线"的经典分割线外观。

trailing_indent：后缘空白

trailing_indent: Optional[Number] = None

Divider后缘（trailing edge，即水平方向结束侧）或VerticalDivider底部（bottom edge）的空白空间大小。与leading_indent配合，实现不对称缩进（例如常见的"标题下方缩进分割线"效果：左侧缩进 16、右侧缩进 0）。

四个数值属性的默认回退逻辑完全对称：控件未显式设置时回退到主题值，主题值也为None时回退到各自的硬编码默认值（leading_indent、trailing_indent默认0.0，thickness默认0.0，space默认16.0）。

在 Theme 中挂载与生效范围

DividerTheme通过Theme.divider_theme属性挂载到全局主题上，定义于 theme.py：

divider_theme: Optional[DividerTheme] = None """ Defines the visual properties of Divider, VerticalDivider, dividers between ListTiles, and dividers between rows in DataTable. """

紧随其后还有一个便捷的平铺属性divider_color（theme.py）：

divider_color: Optional[ColorValue] = None """ Overrides the default color of dividers used in Divider, VerticalDivider, dividers between ListTiles, and between rows in DataTable. """

也就是说，如果你的需求只是"全局换一种分割线颜色"，可以直接用Theme(divider_color=...)一行搞定；如果需要同时调整颜色、线宽、空间与缩进，则用Theme(divider_theme=ft.DividerTheme(...))。

配置方式与 Flet 其他主题一致，两种途径任选其一：

import flet as ft # 方式一：在页面级应用 def main(page: ft.Page): page.theme = ft.Theme( divider_theme=ft.DividerTheme( color=ft.Colors.OUTLINE, thickness=1, space=24, leading_indent=16, trailing_indent=16, ), ) page.add( ft.Column( controls=[ ft.Text("Section A"), ft.Divider(), ft.Text("Section B"), ] ) ) ft.app(main) # 方式二：在 app 级统一注入 # ft.app(main, theme=ft.Theme(divider_color=ft.Colors.GREY_400))

控件属性与主题属性的优先级

DividerTheme的价值在于它只是"兜底默认值"：任何单个分割线控件都可以通过自身属性覆盖主题。以 Divider 为例，其属性文档明确标注了回退链条：

即优先级为：控件显式属性 >DividerTheme对应属性 > 内置默认值。

VerticalDivider 的回退逻辑完全一致，仅把height换成width（DividerTheme.space的语义相应变为纵向宽度），leading_indent/trailing_indent分别对应顶部/底部空白。

实际的优先级代码路径

这种"三明治式"回退并非文档虚构，而是编码在控件属性类型注解与 docstring 中。例如 divider.py 的 color 属性：

color: Optional[ColorValue] = None """ The color to use when painting the line. If `None`, DividerTheme.color is used. """

以及 height 属性：

height: Annotated[Optional[Number], V.ge(0)] = None """ ... If `None`, DividerTheme.space is used. If that's is also `None`, defaults to `16.0`. Raises: ValueError: If height is negative. """

同时注意这些数值属性都带有V.ge(0)校验注解：height、thickness、leading_indent、trailing_indent均不允许为负数，传入负值会抛出ValueError，这也是DividerTheme对应属性在底层被消费时的约束前提。

控件还支持圆角

Divider与VerticalDivider还各有一个主题中没有的radius: Optional[BorderRadiusValue]属性（divider.py），用于给分割线端点设置圆角，属于控件级能力，适合在个别位置做装饰性分割线。

源码实现：@value 与稀疏属性追踪

DividerTheme声明上方只有一个@value装饰器（theme.py），这是 Flet 对非控件值类型（如TextStyle、Duration、Alignment等）的统一处理方式。其实现位于 sdk/python/packages/flet/src/flet/controls/value_types.py：

@dataclass_transform() def value(cls: Optional[type] = None, **dataclass_kwargs: Any) -> Any: """ Decorator for non-control value types to enable sparse `_values` tracking. ... """

@value所做的工作可以概括为：

• 将类转换为@dataclass，使DividerTheme(...)可以用关键字参数按属性构造；
• 通过_install_props为每个属性安装Prop描述符，从而支持稀疏_values追踪——只记录被显式赋值的字段，未设置的字段不进入待同步集合；
• 包装__init__，在构造前注入_values与_dirty两个内部字典，构造完成后清空_dirty，使得"刚创建的对象"与"修改过的对象"在 diff 机制中表现正确；
• 将类注册为Value的子类（元类_ValueMeta与基类Value见 value_types.py），方便运行时isinstance(obj, Value)判断。

这意味着当你把DividerTheme放进Theme并挂到page.theme后，Flet 客户端只需同步实际发生变化的字段，未设置的属性不会产生无意义的传输开销。这一机制与控件树通用的属性 diff 机制一致，是主题对象能够高效随页面更新下发的底层保障。

在布局中的典型用法

DividerTheme通常用于保证整页分割线风格统一。以下是一个把主题与控件覆盖结合使用的完整示例，先给出横向分割线的官方文档示例骨架（见 divider.py 类文档）：

import flet as ft def main(page: ft.Page): page.theme = ft.Theme( divider_theme=ft.DividerTheme( color=ft.Colors.OUTLINE_VARIANT, thickness=1, space=20, leading_indent=8, ), ) page.add( ft.Column( width=240, spacing=10, controls=[ ft.Text("Section A", weight=ft.FontWeight.W_600), ft.Divider(), # 使用主题：颜色/线宽/空间/左缩进全部来自 DividerTheme ft.Text("Section B"), ft.Divider( color=ft.Colors.RED, # 单条分割线覆盖主题颜色 height=50, # 覆盖主题 space thickness=2, leading_indent=20, trailing_indent=20, ), ], ) ) ft.app(main)

纵向场景使用ft.VerticalDivider()，其官方示例（见 vertical_divider.py 类文档）是在Row中分隔两个色块：

ft.Row( width=120, height=60, expand=True, spacing=0, controls=[ ft.Container( bgcolor=ft.Colors.BLUE_GREY_200, alignment=ft.Alignment.CENTER, expand=True, ), ft.VerticalDivider(), ft.Container( bgcolor=ft.Colors.GREY_500, alignment=ft.Alignment.CENTER, expand=True, ), ], )

此时VerticalDivider的线宽、颜色与上下留白同样受DividerTheme支配。

测试验证与进一步探索

仓库的集成测试对分割线控件的属性行为提供了直接验证。sdk/python/packages/flet/integration_tests/controls/material/test_divider.py 中的test_properties用例构造了带全部属性的Divider：

await flet_app.assert_control_screenshot( request.node.name, ft.Divider( color=ft.Colors.RED, height=50, thickness=2, leading_indent=20, trailing_indent=20, ), )

该用例通过assert_control_screenshot将控件渲染结果与基准截图比对，覆盖了color、height、thickness、leading_indent、trailing_indent五个控件属性；test_radius则验证radius圆角分支，test_basic验证无参默认渲染。配套的VerticalDivider测试见 integration_tests/controls/material/test_vertical_divider.py。

如需继续深入，建议按以下路径阅读源码：

• 主题挂载：theme.py 中divider_theme与divider_color
• 控件实现：divider.py 与 vertical_divider.py
• 值类型机制：value_types.py 中@value装饰器
• 集成测试：test_divider.py 与 test_vertical_divider.py

小结

DividerTheme用 5 个属性覆盖了分割线渲染的全部关键维度：color决定颜色，thickness决定线本身粗细，space决定占据的布局空间，leading_indent/trailing_indent决定两端空白。它统一作用于Divider、VerticalDivider、ListTile之间与DataTable行间四类分割线，并遵循"控件属性 > 主题属性 > 内置默认值"的回退顺序，既保证全局风格统一，又保留单点覆盖的灵活性。配合@value装饰器带来的稀疏属性同步机制，它能在零额外开销的前提下，让整个应用的分割线风格一键成型。

• 前端
• 跨平台
• 桌面应用
• 移动开发