Flet DataRow2 数据行控件完全指南行级点击事件、装饰与行高定制【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletDataRow2是 Flet 生态中flet-datatable2扩展包提供的高级数据行控件它在继承 Flet 内置DataRow全部能力的基础上新增了行级on_tap、on_double_tap、on_secondary_tap等交互事件并支持decoration行装饰与specific_row_height独立行高定制常与 DataTable2 与 DataColumn2 配合使用用于构建可排序、可选择、支持粘性表头/固定列的数据表格。读完本文你将掌握DataRow2的全部属性语义、事件触发优先级规则以及如何用官方示例代码搭建一个完整可运行的交互式数据表。一、DataRow2 是什么能力边界与定位DataRow2定义在flet-datatable2扩展包的 datarow2.py 中其类声明为ft.control(DataRow2) class DataRow2(ft.DataRow):从源码结构看它通过ft.control(DataRow2)注册为 Flet 控件并直接继承内置的ft.DataRow。这意味着内置DataRow的所有既有能力单元格cells、选中状态selected、on_select_change选择回调等在DataRow2上全部保留同时在行级别新增了四类交互事件与两类外观属性。需要特别说明的是官方文档页面如 datarow2.md通过 crocodocs 组件动态渲染该类源码中的 docstring 作为 API 参考因此本指南以仓库源码datarow2.py中的真实属性定义为基准展开。DataRow2的定位是作为DataTable2.rows列表的元素使用DataTable2.rows类型为list[Union[ft.DataRow, DataRow2]]参见 datatable2.py即它是整个flet-datatable2数据表格体系DataTable2DataColumn2DataRow2的行组成部分。DataTable2相比内置DataTable提供了粘性表头、可滚动数据行与更灵活的布局源码 docstring 明确说明而DataRow2则负责把交互能力下沉到每一行。二、行级交互事件on_tap 家族DataRow2相比内置DataRow的核心增强在于行级而非单元格级的点击事件。这解决了内置DataTable中点击行为只能挂在单个DataCell上的局限让开发者可以整体感知用户点了这一行。2.1 on_tap单击行on_tap: Optional[ft.EventHandler[ft.TapEvent[DataRow2]]] None当用户单击该行时触发事件对象类型为ft.TapEvent。典型应用是点击行即选中/取消选中官方示例 sortable_and_selectable/main.py 中的做法是def handle_row_selection_change(e: ft.Event[ftd.DataRow2]) - None: e.control.selected not e.control.selected e.control.update()注该示例中DataRow2挂的是on_select_change选择状态变化回调继承自内置DataRowon_tap与它属于不同事件若想用单击行来切换选中只需把同样的逻辑挂到on_tap上即可两者都是行级事件。2.2 on_double_tap双击行on_double_tap: Optional[ft.ControlEventHandler[DataRow2]] None当行被双击时触发。适合双击打开详情/编辑类交互。2.3 on_secondary_tap 与 on_secondary_tap_down右键次点击on_secondary_tap: Optional[ft.ControlEventHandler[DataRow2]] None on_secondary_tap_down: Optional[ft.ControlEventHandler[DataRow2]] None两个事件都对应右键点击secondary tap场景on_secondary_tap在右键释放up时触发on_secondary_tap_down在右键按下down时触发。源码 docstring 特别指出这两个事件是内置DataCell所不具备的在桌面端处理右键菜单等场景时尤其有用。例如可以先用on_secondary_tap_down定位行并弹出ft.ContextMenu再在菜单项上继续操作。2.4 事件触发优先级重要限制上述四个行级事件有一个共同的触发前提源码 docstring 明确警告如果被点击的单元格DataCell上设置了任何点击事件处理器则行级事件不会触发。具体涉及的单元格事件包括继承自ft.DataCellon_tapon_double_tapon_long_presson_tap_cancelon_tap_down也就是说事件优先级是单元格级事件 行级事件一旦某个单元格或整行所有单元格声明了自己的手势处理器手势事件会被单元格消费DataRow2的行级on_tap/on_double_tap/on_secondary_tap/on_secondary_tap_down均不会被调用。在设计交互时请避免在同一行内同时使用单元格级与行级点击事件以免行级事件静默失效。这一规则在 Flutter 端实现中也有对应印证DataRow2的 Flutter 适配层datatable2.dart对onDoubleTap、onTap、onSecondaryTap、onSecondaryTapDown的注册以布尔开关row.getBool(on_double_tap, false)等为依据而 Dart 端data_table_2的DataRow2组件本身规定了行级手势与单元格手势的共存约束Python 侧只是忠实映射了这一行为。三、外观定制decoration 与 specific_row_height3.1 decoration整行装饰decoration: Optional[ft.BoxDecoration] None为整行应用ft.BoxDecoration装饰背景色、边框、圆角、阴影等。典型的用法示例ftd.DataRow2( decorationft.BoxDecoration( colorft.Colors.SURFACE_VARIANT, borderft.Border.all(1, ft.Colors.OUTLINE), border_radius8, ), cells[...], )重要注意点源码 docstring 明确指出一旦提供了decorationflet.DataTable.divider_thickness行分隔线粗细将不再生效。因为行装饰尤其是带背景色/边框的装饰会覆盖掉分隔线的视觉呈现。所以在使用decoration时不要依赖divider_thickness来实现行间分隔。3.2 specific_row_height单行独立高度specific_row_height: Optional[ft.Number] None为当前行指定独立的高度数值单位为逻辑像素。其语义是行级覆盖如果未设置则回退到flet_datatable2.DataTable2.data_row_height设置了则以本行的specific_row_height为准。这允许在同一张表中混合不同高度的行例如重点行加高。官方示例 sortable_and_selectable/main.py 中所有行统一设置了specific_row_height50ftd.DataRow2( specific_row_height50, on_select_changehandle_row_selection_change, cells[ ft.DataCell(contentft.Text(dessert.name)), ft.DataCell(contentft.Text(dessert.calories)), # ... 其余单元格 ], )与DataTable2侧的data_row_heightdatatable2.py配合形成表级默认行高 行级覆盖行高的两级行高体系。值得留意的是DataTable2本身不支持父类DataTable的data_row_min_height与data_row_max_height属性源码中以initFalse的字段屏蔽行高统一走data_row_height/specific_row_height这是它与内置DataTable的一个行为差异。四、实战用 DataRow2 构建可排序可选择的甜品数据表结合官方扩展示例下面给出一个完整、可运行的实战案例综合运用DataRow2的行级事件、DataColumn2的列尺寸/排序以及DataTable2的表格级配置。完整源码位于 sortable_and_selectable/main.py这里展示其核心结构4.1 数据模型dataclass class Dessert: name: str calories: float fat: float carbs: float protein: float sodium: float calcium: float iron: float4.2 构建行DataRow2 的典型用法def get_data_rows(items: list) - list[ftd.DataRow2]: return [ ftd.DataRow2( specific_row_height50, on_select_changehandle_row_selection_change, cells[ ft.DataCell(contentft.Text(dessert.name)), ft.DataCell(contentft.Text(dessert.calories)), ft.DataCell(contentft.Text(dessert.fat)), ft.DataCell(contentft.Text(dessert.carbs)), ft.DataCell(contentft.Text(dessert.protein)), ft.DataCell(contentft.Text(dessert.sodium)), ft.DataCell(contentft.Text(dessert.calcium)), ft.DataCell(contentft.Text(dessert.iron)), ], ) for dessert in items ]这里的handle_row_selection_change就是 2.1 节展示的行选中切换回调。注意示例中单元格全部使用ft.DataCell(contentft.Text(...))且没有设置任何单元格级手势事件因此行级事件不会被单元格抢占——这正是DataRow2行级交互能够正常工作的前提。4.3 组装 DataTable2table ftd.DataTable2( expandTrue, show_checkbox_columnTrue, column_spacing0, heading_row_colorft.Colors.SECONDARY_CONTAINER, horizontal_margin12, sort_ascendingTrue, bottom_margin10, min_width600, on_select_alllambda _: print(All selected), columnsget_data_columns(), rowsget_data_rows(sorted_desserts), ) page.add(ft.SafeArea(expandTrue, contenttable))4.4 运行方式示例目录带有pyproject.toml运行前需先安装flet与flet-datatable2pip install flet flet-datatable2或使用uvuv add flet flet-datatable2然后执行python main.py应用启动后你将得到一个支持按任意列排序点击表头触发on_sort、支持复选框批量选择、表头吸顶、行高统一为 50、最小宽度 600 可横向滚动的数据表。运行效果动画见 media/sortable_and_selectable.gif位于同一示例目录。五、平台支持与相关资源平台支持flet-datatable2基于 Flutter 社区data_table_2包实现见 README.md在 Windows、macOS、Linux、iOS、Android、Web 六大平台均可用。Python 版本要求flet-datatable2要求 Python 3.10见 pyproject.toml。源码位置Python 侧实现位于 datarow2.pyFlutter 适配层位于 datatable2.dart。更多示例扩展示例目录 sdk/python/examples/extensions/datatable2 下还包含column_widths列宽定制与empty_state空数据占位两个示例可配合DataRow2进一步学习列宽比例与空态展示。配套文档DataTable2 与 DataColumn2 的 API 参考页面与本页同属flet-datatable2控件文档体系建议一并阅读以理解表格整体行为。六、核心要点速查属性/事件类型说明与限制on_tapft.EventHandler[ft.TapEvent[DataRow2]]单击行触发单元格级手势存在时不触发on_double_tapft.ControlEventHandler[DataRow2]双击行触发同上受单元格级手势影响on_secondary_tapft.ControlEventHandler[DataRow2]右键抬起触发DataCell不具备此事件on_secondary_tap_downft.ControlEventHandler[DataRow2]右键按下触发适合桌面端右键菜单场景decorationOptional[ft.BoxDecoration]整行装饰设置后divider_thickness失效specific_row_heightOptional[ft.Number]单行高度未设置时回退到DataTable2.data_row_heightselected/on_select_change继承自ft.DataRow行选中状态与变更回调行为与内置DataRow一致小结DataRow2的核心价值在于把行提升为完整的事件与样式载体——行级单击/双击/右键事件补足了内置DataTable在整行交互上的空缺尤其利于桌面端右键菜单decoration与specific_row_height则提供了行维度的视觉与布局控制。使用时要牢记两条约束一是单元格手势会抢占行级手势二是设置decoration后divider_thickness不再生效。掌握这两条边界即可在DataTable2中放心地构建具备丰富行级交互的数据表格。【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考