Flet Segment 控件详解使用 Segment 构建 SegmentedButton 分段按钮【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletflet.Segment是 Flet 中分段按钮SegmentedButton的一个分段单元用于把一组互斥或可多选的选项以标签 图标的形式并排展示。本文以 website/docs/controls/segment.md 文档页为核心结合仓库中的 Python 源码、Dart 端渲染实现与官方示例完整讲解Segment的每个属性、校验规则以及它和SegmentedButton配合使用时的全部关键行为读完即可在自己的 Flet 应用中落地实现单选/多选分段控件。Segment 在 Flet 中的定位Segment不是一个独立展示的控件而是专门为 SegmentedButton 服务的零件SegmentedButton通过segments属性接收一个Segment列表每个Segment代表一个可点击的分段。二者定义在同一个源码文件中Python 端sdk/python/packages/flet/src/flet/controls/material/segmented_button.pyDartFlutter渲染端packages/flet/lib/src/controls/segmented_button.dart从源码看Segment类通过control(Segment)装饰器注册为 Flet 控件直接继承自Controlsegmented_button.py并不继承LayoutControl说明它只承载数据值、图标、标签真正负责布局与交互的是SegmentedButton。对应的 Flutter 端SegmentedButton在构建时会遍历每个Segment并转换成 Flutter 的ButtonSegment见 segmented_button.dart。Segment 的三个核心属性Segment的全部公开属性如下表所示属性类型是否必填说明valuestr是标识该分段的唯一值供selected列表引用iconIconData \| ControlOptional否显示在分段中的图标通常是Iconlabelstr \| ControlOptional否显示在分段中的标签通常是Textvalue分段的身份标识value是一个字符串用于识别这个分段源码 docstring 原文Used to identify this segment见 segmented_button.py。它并不直接渲染到界面上而是被SegmentedButton.selected列表引用例如selected[1, 4]表示值为1和4的两个分段处于选中状态。在 Dart 端value被直接传给ButtonSegment(value: ...)segmented_button.dart作为选中态匹配的键。icon 与 label分段的内容icon通常是Icon控件如ft.Icon(ft.Icons.LOOKS_ONE)显示在分段前部label通常是Text控件或普通字符串显示分段文字如ft.Text(One)。源码 docstring 明确指出如果icon和label都未设置或不可见构造Segment时会抛出ValueErrorsegmented_button.py。这一约束由__validation_rules__校验规则强制执行详见下文源码级校验规则。类型别名说明icon的类型是IconDataOrControllabel的类型是StrOrControl这两个类型别名定义在同包的类型模块中见 segmented_button.py 的导入。其中StrOrControl表示字符串或控件意味着label既可以传一个普通字符串如labelOne也可以传一个Text控件以获得更精细的样式控制。官方示例单选择与多选择分段按钮仓库在 sdk/python/examples/controls/material/segmented_button/single_multiple_selection/ 目录下提供了完整的可运行示例含 main.py 和配套的 pyproject.toml该示例同时演示了多选与单选两种模式import flet as ft def main(page: ft.Page): def handle_selection_change(e: ft.Event[ft.SegmentedButton]): print(e) page.add( ft.SafeArea( contentft.Column( controls[ ft.SegmentedButton( on_changehandle_selection_change, selected_iconft.Icon(ft.Icons.CHECK_SHARP), selected[1, 4], allow_empty_selectionTrue, allow_multiple_selectionTrue, segments[ ft.Segment( value1, labelft.Text(One), iconft.Icon(ft.Icons.LOOKS_ONE), ), ft.Segment( value2, labelft.Text(Two), iconft.Icon(ft.Icons.LOOKS_TWO), ), ft.Segment( value3, labelft.Text(Three), iconft.Icon(ft.Icons.LOOKS_3), ), ft.Segment( value4, labelft.Text(Four), iconft.Icon(ft.Icons.LOOKS_4), ), ], ), ft.SegmentedButton( on_changehandle_selection_change, selected_iconft.Icon(ft.Icons.CHECK_SHARP), selected[2], allow_multiple_selectionFalse, segments[ ft.Segment( value1, labelft.Text(One), iconft.Icon(ft.Icons.LOOKS_ONE), ), ft.Segment( value2, labelft.Text(Two), iconft.Icon(ft.Icons.LOOKS_TWO), ), ft.Segment( value3, labelft.Text(Three), iconft.Icon(ft.Icons.LOOKS_3), ), ft.Segment( value4, labelft.Text(Four), iconft.Icon(ft.Icons.LOOKS_4), ), ], ), ] ) ) ) if __name__ __main__: ft.run(main)示例中有两点值得注意多选模式第一个按钮allow_multiple_selectionTrue、allow_empty_selectionTrue初始选中[1, 4]两个分段点击已选中的分段会取消选中允许全部取消单选模式第二个按钮allow_multiple_selectionFalse默认值初始选中[2]同一时刻只允许一个分段被选中。on_change回调参数是ft.Event[ft.SegmentedButton]通过e.data拿到当前选中的分段值列表。Dart 端在选中变化时执行triggerEvent(change, s)并向 Python 端回写selected属性segmented_button.dart。与 Segment 协同的 SegmentedButton 关键属性虽然segment.md文档页聚焦于Segment本身但Segment的所有行为都由SegmentedButton的以下属性驱动二者必须在同一文件segmented_button.py中配套理解selected 与选择模式约束selected: list[str]当前选中的Segment.value列表默认[]。用户点击分段时由框架自动更新也可以通过编程方式设置初始值。allow_empty_selection: bool默认False。为True时允许没有任何分段被选中selected可以为空为False时至少需要一个分段被选中——如果用户点击唯一选中的分段它不会被取消且on_change不会被触发。allow_multiple_selection: bool默认False。为True时允许多选点击已选分段会取消选中为False时单选选中新分段会取消之前的选中。这三者存在强校验关系源码__validation_rules__明确给出segmented_button.pyselected为空时必须allow_empty_selectionTrue否则抛ValueError提示 allow_empty_selection must be True for selected to be emptyselected超过一项时必须allow_multiple_selectionTrue否则抛ValueError提示 allow_multiple_selection must be True for selected to have more than one itemsegments至少包含一个可见的Segment否则抛ValueErrorV.visible_controls(min_count1)见 segmented_button.py。selected_icon 与 show_selected_iconselected_icon: IconDataOrControl用于标识已选中状态的图标控件默认是一个CHECK图标Icons.CHECK。若show_selected_iconTrue该图标会显示在选中分段的label之前并替换该分段自身的icon若指定了的话。show_selected_icon: bool默认True控制选中图标是否显示为False时selected_icon完全不参与渲染。外观与布局style: ButtonStyle自定义按钮外观前景色、背景色、圆角、阴影、边距等。Dart 端通过getButtonStyle解析默认前景色取主题colorScheme.primary、背景色取colorScheme.surfaceMaterial 3 下默认形状为StadiumBorder胶囊形Material 2 下为圆角 4 的圆角矩形segmented_button.dart。direction: Axis分段的排布方向默认Axis.HORIZONTAL水平可设为Axis.VERTICAL实现纵向排列。padding: PaddingValue默认None时按钮采用内容固有尺寸一旦指定按钮会按该 padding 扩展以填满父容器空间。源码级校验规则与渲染链路Python 端Segment 的可见性校验Segment的__validation_rules__使用V.ensure(...)定义了一条关键规则segmented_button.py校验通过的条件是——icon是IconData或icon是控件且visibleTrue或者label是字符串或label是控件且visibleTrue。只要icon与label二者中有一个已设置且可见校验即通过否则抛出 at least icon or label must be set and visible 的ValueError。这意味着Segment(value1, labelOne)合法有字符串标签Segment(value1, iconft.Icon(...))合法有图标Segment(value1)不合法直接抛异常。Dart 端错误态与渲染Flutter 侧在构建SegmentedButton前会做三重防御性校验segmented_button.dart任一不满足都会渲染ErrorControl错误占位segments为空 → SegmentedButton.segments must be contain at least one visible segmentselected为空但allow_empty_selectionFalse→ SegmentedButton.selected must contain at least one value...单选模式下selected数量不等于 1 → SegmentedButton.selected must contain exactly one value...多选模式下selected数量超过分段数 → The length of SegmentedButton.selected must be less than or equal to the number of visible segments。正常的渲染路径则是遍历每个Segment把value、enabled继承自Control.disabled、tooltip、icon、label组装成 Flutter 的ButtonSegment然后交给 Material 的SegmentedButton控件segmented_button.dart。其中direction和expandedInsets对应 Python 的padding分别映射到 Flutter 的direction与expandedInsets参数。常见用法要点初始化默认选中通过selected[2]设定初始选中项无需等待用户交互监听选择变化on_change回调中的e.data是选中分段value的列表即使单选模式也是列表分段禁用Segment继承Control.disabled属性禁用后该分段不可点击且tooltip不会显示Dart 端在enabledfalse时传tooltip: null见 segmented_button.dart纵向分段设置directionft.Axis.VERTICAL即可把分段改为纵向排列自定义选中图标selected_iconft.Icon(ft.Icons.CHECK_SHARP)可把默认的CHECK换成任意 Material 图标。小结flet.Segment是SegmentedButton的最小组成单元它通过value提供身份、通过icon/label提供内容并受到二者至少其一可见的硬性校验。要真正使用它需要与SegmentedButton的selected、allow_empty_selection、allow_multiple_selection、selected_icon、show_selected_icon、direction等属性配合Python 端负责声明式配置与校验Dart 端负责映射为 Flutter 原生ButtonSegment并回传选择事件。文中所有示例与行为均可对照以下仓库路径进一步验证Segment / SegmentedButton Python 源码sdk/python/packages/flet/src/flet/controls/material/segmented_button.pyFlutter 渲染实现packages/flet/lib/src/controls/segmented_button.dart官方单/多选示例sdk/python/examples/controls/material/segmented_button/single_multiple_selection/main.pySegmentedButton 文档页website/docs/controls/segmentedbutton/index.md【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
