主题
DataTable 继承自：LayoutControl, Control, BaseControl
Material Design 数据表格。
示例：
python
ft.DataTable(
columns=[
ft.DataColumn(label=ft.Text("Name")),
ft.DataColumn(label=ft.Text("Role")),
],
rows=[
ft.DataRow(
cells=[
ft.DataCell(ft.Text("Alice")),
ft.DataCell(ft.Text("Engineer")),
]
),
ft.DataRow(
cells=[
ft.DataCell(ft.Text("Bob")),
ft.DataCell(ft.Text("Designer")),
]
),
],
)提示
这张表格不够用了？它更强大的表亲 DataTable2（来自 flet-datatable2 扩展包）提供了粘性表头、固定行／列、按列设置宽度（固定宽度或相对的 S/M/L），以及一些其他好用功能 —— 对大型或宽表很实用。
示例
python
import flet as ft
def main(page: ft.Page):
page.add(
ft.SafeArea(
content=ft.DataTable(
expand=True,
columns=[
ft.DataColumn(label=ft.Text("First name")),
ft.DataColumn(label=ft.Text("Last name")),
ft.DataColumn(label=ft.Text("Age"), numeric=True),
],
rows=[
ft.DataRow(
cells=[
ft.DataCell(ft.Text("John")),
ft.DataCell(ft.Text("Smith")),
ft.DataCell(ft.Text("43")),
],
),
ft.DataRow(
cells=[
ft.DataCell(ft.Text("Jack")),
ft.DataCell(ft.Text("Brown")),
ft.DataCell(ft.Text("19")),
],
),
ft.DataRow(
cells=[
ft.DataCell(ft.Text("Alice")),
ft.DataCell(ft.Text("Wong")),
ft.DataCell(ft.Text("25")),
],
),
],
),
)
)
if __name__ == "__main__":
ft.run(main)
python
import flet as ft
def _cell(label: str, color: str = ft.Colors.SURFACE_CONTAINER_HIGHEST) -> ft.DataCell:
return ft.DataCell(
ft.Container(
width=90,
height=32,
alignment=ft.Alignment.CENTER,
bgcolor=color,
border=ft.Border.all(1, ft.Colors.BLACK_26),
content=ft.Text(label, size=12, weight=ft.FontWeight.W_600),
)
)
def main(page: ft.Page):
page.scroll = ft.ScrollMode.AUTO
page.horizontal_alignment = ft.CrossAxisAlignment.CENTER
page.theme_mode = ft.ThemeMode.DARK
def update_spacing() -> None:
table.horizontal_margin = horizontal_margin_slider.value
table.column_spacing = column_spacing_slider.value
table.update()
def handle_spacing_change(_: ft.Event[ft.Slider]) -> None:
update_spacing()
def set_preset(horizontal_margin: float, column_spacing: float) -> None:
horizontal_margin_slider.value = horizontal_margin
column_spacing_slider.value = column_spacing
horizontal_margin_slider.update()
column_spacing_slider.update()
update_spacing()
horizontal_margin_slider = ft.Slider(
key="horizontal_margin_slider",
min=0,
max=40,
divisions=40,
value=16,
label="{value}",
on_change=handle_spacing_change,
)
column_spacing_slider = ft.Slider(
key="column_spacing_slider",
min=0,
max=40,
divisions=40,
value=16,
label="{value}",
on_change=handle_spacing_change,
)
table = ft.DataTable(
border=ft.Border.all(1, ft.Colors.ON_SURFACE_VARIANT),
horizontal_margin=horizontal_margin_slider.value,
column_spacing=column_spacing_slider.value,
horizontal_lines=ft.BorderSide(1, ft.Colors.ON_SURFACE_VARIANT),
vertical_lines=ft.BorderSide(1, ft.Colors.ON_SURFACE_VARIANT),
heading_row_height=40,
data_row_min_height=40,
data_row_max_height=40,
columns=[
ft.DataColumn(label="Col A"),
ft.DataColumn(label="Col B"),
ft.DataColumn(label="Col C"),
],
rows=[
ft.DataRow(cells=[_cell("A1"), _cell("B1"), _cell("C1")]),
ft.DataRow(cells=[_cell("A2"), _cell("B2"), _cell("C2")]),
],
)
page.appbar = ft.AppBar(title="DataTable spacing")
page.add(
ft.SafeArea(
content=ft.Column(
horizontal_alignment=ft.CrossAxisAlignment.CENTER,
controls=[
ft.Container(
width=520,
padding=12,
border=ft.Border.all(1, ft.Colors.OUTLINE_VARIANT),
border_radius=8,
content=ft.Column(
horizontal_alignment=ft.CrossAxisAlignment.CENTER,
controls=[
ft.Text("horizontal_margin (outer edges)"),
horizontal_margin_slider,
ft.Text("column_spacing (between columns)"),
column_spacing_slider,
ft.Row(
wrap=True,
controls=[
ft.FilledButton(
"Reset",
on_click=lambda _: set_preset(16, 16),
),
ft.OutlinedButton(
"Compact preset",
on_click=lambda _: set_preset(0, 0),
),
ft.OutlinedButton(
"Spacious preset",
on_click=lambda _: set_preset(24, 32),
),
],
),
],
),
),
table,
],
),
)
)
if __name__ == "__main__":
ft.run(main)
python
import flet as ft
def main(page: ft.Page):
page.add(
ft.SafeArea(
content=ft.DataTable(
width=560,
data_row_min_height=48,
data_row_max_height=float("inf"),
columns=[
ft.DataColumn(label="Description"),
ft.DataColumn(label="Notes"),
],
rows=[
ft.DataRow(
cells=[
ft.DataCell("TWO lines visible without overflow"),
ft.DataCell("Line 1\nLine 2"),
],
),
ft.DataRow(
cells=[
ft.DataCell("FOUR lines visible without overflow"),
ft.DataCell("Line 1\nLine 2\nLine 3\nLine 4"),
],
),
ft.DataRow(
cells=[
ft.DataCell("FIVE lines visible without overflow"),
ft.DataCell("Line 1\nLine 2\nLine 3\nLine 4\nLine 5"),
],
),
],
),
)
)
if __name__ == "__main__":
ft.run(main)
python
import flet as ft
def main(page: ft.Page):
page.scroll = ft.ScrollMode.AUTO
inventory_items = [
{"id": 1, "name": "Alpha", "qty": 4},
{"id": 2, "name": "Bravo", "qty": 9},
{"id": 3, "name": "Charlie", "qty": 2},
{"id": 4, "name": "Delta", "qty": 6},
{"id": 5, "name": "Echo", "qty": 3},
{"id": 6, "name": "Foxtrot", "qty": 8},
{"id": 7, "name": "Golf", "qty": 1},
{"id": 8, "name": "Hotel", "qty": 7},
{"id": 9, "name": "India", "qty": 5},
{"id": 10, "name": "Juliet", "qty": 10},
]
displayed_items = list(inventory_items)
selected_item_ids: set[int] = {1, 3, 5}
sort_key_for_column = {
0: lambda item: str(item["name"]).lower(),
1: lambda item: int(item["qty"]),
}
def build_rows(items: list[dict[str, int | str]]) -> list[ft.DataRow]:
return [
ft.DataRow(
selected=item["id"] in selected_item_ids,
on_select_change=handle_row_selection_change,
data=item["id"],
cells=[
ft.DataCell(ft.Text(item["name"])),
ft.DataCell(ft.Text(str(item["qty"]))),
],
)
for item in items
]
def refresh_table_rows() -> None:
table.rows = build_rows(displayed_items)
table.update()
def handle_row_selection_change(e: ft.Event[ft.DataRow]) -> None:
row = e.control
item_id = row.data
is_selected = e.data
if is_selected:
selected_item_ids.add(item_id)
else:
selected_item_ids.discard(item_id)
row.selected = is_selected
row.update()
def handle_select_all(e: ft.Event[ft.DataTable]) -> None:
if e.data:
selected_item_ids.update(int(item["id"]) for item in displayed_items)
else:
selected_item_ids.clear()
refresh_table_rows()
def handle_column_sort(e: ft.DataColumnSortEvent) -> None:
displayed_items.sort(
key=sort_key_for_column[e.column_index],
reverse=not e.ascending,
)
table.sort_column_index = e.column_index
table.sort_ascending = e.ascending
refresh_table_rows()
table = ft.DataTable(
width=700,
bgcolor=ft.Colors.SURFACE_CONTAINER_LOW,
border=ft.Border.all(1, ft.Colors.OUTLINE_VARIANT),
border_radius=10,
vertical_lines=ft.border.BorderSide(1, ft.Colors.OUTLINE_VARIANT),
horizontal_lines=ft.border.BorderSide(1, ft.Colors.OUTLINE_VARIANT),
sort_column_index=0,
sort_ascending=True,
heading_row_color=ft.Colors.SURFACE_CONTAINER_HIGHEST,
heading_row_height=100,
data_row_color={
ft.ControlState.HOVERED: ft.Colors.with_opacity(0.08, ft.Colors.PRIMARY),
ft.ControlState.SELECTED: ft.Colors.with_opacity(0.14, ft.Colors.PRIMARY),
},
show_checkbox_column=True,
on_select_all=handle_select_all,
divider_thickness=1,
column_spacing=200,
columns=[
ft.DataColumn(
label=ft.Text("Item"),
on_sort=handle_column_sort,
),
ft.DataColumn(
label=ft.Text("Quantity"),
tooltip="Numeric quantity",
numeric=True,
on_sort=handle_column_sort,
),
],
rows=build_rows(displayed_items),
)
page.add(
ft.SafeArea(
content=table,
)
)
if __name__ == "__main__":
ft.run(main)
python
import flet as ft
def main(page: ft.Page):
def handle_row_selection_change(e: ft.Event[ft.DataRow]) -> None:
if e.control.data == 1:
row1.selected = not row1.selected
elif e.control.data == 2:
row2.selected = not row2.selected
elif e.control.data == 3:
row3.selected = not row3.selected
table.update()
def handle_column_sort(e: ft.DataColumnSortEvent) -> None:
if e.control.data in [1, 2]:
print(f"{e.column_index}, {e.ascending}")
table.sort_ascending = e.ascending
table.update()
table = ft.DataTable(
width=700,
bgcolor=ft.Colors.TEAL_ACCENT_200,
border=ft.Border.all(2, ft.Colors.RED_ACCENT_200),
border_radius=10,
vertical_lines=ft.border.BorderSide(3, ft.Colors.BLUE_600),
horizontal_lines=ft.border.BorderSide(1, ft.Colors.GREEN_600),
sort_column_index=0,
sort_ascending=True,
heading_row_color=ft.Colors.BLACK_12,
heading_row_height=100,
data_row_color={ft.ControlState.HOVERED: "0x30FF0000"},
show_checkbox_column=True,
divider_thickness=0,
column_spacing=200,
columns=[
ft.DataColumn(
label=ft.Text("Column 1"),
tooltip="This is the first column",
data=1,
on_sort=handle_column_sort,
),
ft.DataColumn(
label=ft.Text("Column 2"),
tooltip="This is a second column",
numeric=True,
data=2,
on_sort=handle_column_sort,
),
],
rows=[
row1 := ft.DataRow(
cells=[ft.DataCell(ft.Text("A")), ft.DataCell(ft.Text("1"))],
selected=True,
on_select_change=handle_row_selection_change,
data=1,
),
row2 := ft.DataRow(
cells=[ft.DataCell(ft.Text("B")), ft.DataCell(ft.Text("2"))],
selected=False,
on_select_change=handle_row_selection_change,
data=2,
),
row3 := ft.DataRow(
cells=[ft.DataCell(ft.Text("C")), ft.DataCell(ft.Text("3"))],
selected=False,
on_select_change=handle_row_selection_change,
data=3,
),
],
)
page.add(
ft.SafeArea(
content=table,
)
)
if __name__ == "__main__":
ft.run(main)
属性
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columns | list[DataColumn] | 必填 | 描述表格列的 DataColumn 控件列表。 抛出异常： ValueError：如果没有可见的 columns。 |
rows | list[DataRow] | [] | 定义表格行的 DataRow 控件列表。 抛出异常： ValueError：如果任何可见行包含的可见 DataCell 数量与可见 columns 的数量不一致。 |
sort_ascending | bool | False | sort_column_index 所指的列（如果存在）是否按升序排序。 如果为 True，顺序为升序（即当前排序列值最小的行排在表格最前）。 如果为 False，顺序为降序（即当前排序列值最小的行排在表格最后）。 |
show_checkbox_column | bool | False | 控件是否为可选中的行显示复选框。 如果为 True，每个可选中行的开头都会放置一个复选框。但是，如果没有任何行设置了 on_select_change，即使此值为 True，也不会放置复选框。 如果为 False，所有行都不显示复选框。 |
sort_column_index | Optional[int] | None | 当前主排序键所在的列。 如果指定，表示所指列是数据排序所依据的列。该数字必须对应 columns 中相关列的索引。 设置此项会让相关列显示排序指示器。 当此属性为 None 时，表示表格的排序顺序不对应任何列。 抛出异常： ValueError：如果它相对于可见 columns 超出范围。 |
show_bottom_border | bool | False | 是否显示表格底部的边框。 默认情况下底部不显示边框，以便为装饰（decoration）定义的表格边框留出空间。 |
border | Optional[Border] | None | 表格周围的边框。 |
border_radius | Optional[BorderRadiusValue] | None | 边框圆角。 |
horizontal_lines | Optional[BorderSide] | None | 设置行之间水平线的颜色和宽度。 |
vertical_lines | Optional[BorderSide] | None | 设置列之间垂直线的颜色和宽度。 |
checkbox_horizontal_margin | Optional[Number] | None | 复选框周围的水平外边距（如果显示复选框）。 |
column_spacing | Optional[Number] | None | 每个数据列内容之间的水平外边距。 |
data_row_color | Optional[ControlStateValue[ColorValue]] | None | 数据行的背景颜色。 实际生效的背景颜色可以取决于 ControlState 状态，即该行是选中、按下、悬停、聚焦、禁用还是启用。该颜色会作为叠加层绘制在行上。为确保行的 InkWell 可见（在按下、悬停和聚焦时），建议使用半透明背景色。 |
data_row_min_height | Annotated[Optional[Number], V.le_field('data_row_max_height')] | None | 每行（不含包含列标题的行）的最小高度。 默认为 48.0。 抛出异常： ValueError：如果它不小于或等于 data_row_max_height。 |
data_row_max_height | Annotated[Optional[Number], V.ge_field('data_row_min_height')] | None | 每行（不含包含列标题的行）的最大高度。设为 float("inf") 可使每行高度随其内容自动调整。 默认为 48.0。 抛出异常： ValueError：如果它不大于或等于 data_row_min_height。 |
data_text_style | Optional[TextStyle] | None | 数据 rows 的文本样式。 |
bgcolor | Optional[ColorValue] | None | 此表格的背景颜色。 |
gradient | Optional[Gradient] | None | 此表格的背景渐变。 |
divider_thickness | Annotated[Number, V.ge(0)] | 1.0 | 出现在 rows 之间的分隔线宽度。 抛出异常： ValueError：如果它不大于或等于 0。 |
heading_row_color | Optional[ControlStateValue[ColorValue]] | None | 标题行的背景颜色。 实际生效的背景颜色可以取决于 ControlState 状态，即排序时该行是按下、悬停还是聚焦。该颜色会作为叠加层绘制在行上。为确保行的 InkWell 可见（在按下、悬停和聚焦时），建议使用半透明颜色。 |
heading_row_height | Optional[Number] | None | 标题行的高度。 |
heading_text_style | Optional[TextStyle] | None | 标题行的文本样式。 |
horizontal_margin | Optional[Number] | None | 此表格边缘与每行第一个和最后一个单元格内容之间的水平外边距。 当显示复选框时，它也是复选框与第一个数据列内容之间的外边距。 |
clip_behavior | ClipBehavior | ClipBehavior.NONE | 定义此表格内容的裁剪方式。 |
width | Optional[Number] | None | 控件的强制宽度（以虚拟像素为单位）。 |
height | Optional[Number] | None | 控件的强制高度（以虚拟像素为单位）。 |
left | Optional[Number] | None | 子控件左边缘相对于 Stack 左侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。 |
top | Optional[Number] | None | 子控件上边缘相对于 Stack 顶部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。 |
right | Optional[Number] | None | 子控件右边缘相对于 Stack 右侧的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。 |
bottom | Optional[Number] | None | 子控件下边缘相对于 Stack 底部的内缩距离。 注意： 仅当此控件是以下之一的后代时才生效： Stack 控件、overlay 列表。 |
align | Optional[Alignment] | None | 控件在其父级中的对齐方式。 |
margin | Optional[MarginValue] | None | 设置控件的外边距。 |
rotate | Optional[RotateValue] | None | 围绕控件中心旋转来变换此控件。 rotate 属性的值可以是以下类型之一： * number —— 顺时针旋转的弧度值。整圈 360° 为 math.pi * 2 弧度，90° 为 pi / 2，45° 为 pi / 4，以此类推。 * Rotate —— 允许同时指定旋转 angle 和 alignment，即旋转中心的位置。 示例： python ft.Image( src="https://picsum.photos/100/100", width=100, height=100, border_radius=5, rotate=Rotate(angle=0.25 * pi, alignment=ft.Alignment.CENTER_LEFT) ) |
scale | Optional[ScaleValue] | None | 沿二维平面缩放此控件。默认缩放因子为 1.0，表示不缩放。 例如，将此属性设为 0.5 会让控件缩小一半，而设为 2.0 则会放大一倍。 通过将 Control.scale 属性设为 Scale 类的实例，可以为 x 和 y 轴指定不同的缩放倍数。可以指定 scale，或者指定 scale_x 和 scale_y，但不能同时指定全部。 示例： python ft.Image( src="https://picsum.photos/100/100", width=100, height=100, border_radius=5, scale=ft.Scale(scale_x=2, scale_y=0.5) ) |
offset | Optional[OffsetValue] | None | 在绘制控件之前应用平移变换。 平移量表示为按控件尺寸缩放的 Offset。例如，Offset(x=0.25, y=0) 会使控件沿水平方向平移其宽度的四分之一。 示例 下面的示例把容器显示在 Stack 的 0, 0 左上角，因为变换对控件应用了 -1 * 100, -1 * 100（即 offset * control's size）的水平与垂直平移： python import flet as ft def main(page: ft.Page): page.add( ft.Stack( width=1000, height=1000, controls=[ ft.Container( bgcolor=ft.Colors.RED, width=100, height=100, left=100, top=100, offset=ft.Offset(-1, -1), ) ], ) ) ft.run(main) |
flip | Optional[Flip] | None | 水平方向和/或垂直方向翻转此控件。 设为 Flip 的实例即可沿 x 轴、y 轴或两者镜像翻转。 |
transform | Optional[Transform] | None | 对此控件应用通用矩阵变换。 设为带 Matrix4 记录的 Transform 实例，用以描述任意的变换序列。 |
aspect_ratio | Optional[Number] | None | 控件的宽高比，定义为 width 与 height 的比值。 注意： 在当前实现中，如果设置了 aspect_ratio，同一控件上的 width 和 height 将在最终渲染尺寸中被忽略。 |
animate_opacity | Optional[AnimationValue] | None | 启用 opacity 属性的隐式动画。 更多信息见此处。 |
animate_size | Optional[AnimationValue] | None | 启用此控件尺寸的隐式动画。 如果设置了 width 或 height，则这些维度的变化会以动画呈现。如果两者都未设置，则对控件自然尺寸的变化进行动画。 更多信息见此处。 |
animate_position | Optional[AnimationValue] | None | 启用定位属性（left、right、top 和 bottom）的隐式动画。 更多信息见此处。 |
animate_align | Optional[AnimationValue] | None | 启用 align 属性的隐式动画。 更多信息见此处。 |
animate_margin | Optional[AnimationValue] | None | 启用 margin 属性的隐式动画。 更多信息见此处。 |
animate_rotation | Optional[AnimationValue] | None | 启用 rotate 属性的隐式动画。 更多信息见此处。 |
animate_scale | Optional[AnimationValue] | None | 启用 scale 属性的隐式动画。 更多信息见此处。 |
animate_offset | Optional[AnimationValue] | None | 启用 offset 属性的隐式动画。 更多信息见此处。 |
size_change_interval | int | 10 | on_size_change 事件的采样间隔（毫秒）。 设为 0 时，每次变化都会立即调用 on_size_change。 |
expand | Annotated[Optional[Union[bool, int]], V.instance_of((bool, int))] | None | 指定此控件是否／如何扩展以填满父布局中的可用空间。 更多信息见此处。 注意： 仅当此控件的直接父级是以下控件或其子类时才生效：Column、Row、View、Page。 抛出异常： ValueError：如果它不是 bool 或 int 类型。 |
expand_loose | bool | False | 允许控件在主轴方向有可用空间时扩展，但不要求它填满所有可用空间。 更多信息见此处。 注意： 如果 expand_loose 为 True，则仅在以下条件满足时才生效： - expand 不为 None，且 - 此控件的直接父级是以下控件或其子类之一：Column、Row、View、Page。 |
col | ResponsiveNumber | 12 | 如果此控件的父级是 ResponsiveRow，则此属性决定该控件在屏幕上跨越多少虚拟列。 可以是一个数字，也可以是一个按断点配置不同值的字典，例如 col={"sm": 6}。 值为 0 时会在该断点隐藏控件，因此它不会占用父级 ResponsiveRow 中的任何列。 此控件默认跨越 12 个虚拟列。 | 断点 | 尺寸 | |---|---| | xs | <576px | | sm | ≥576px | | md | ≥768px | | lg | ≥992px | | xl | ≥1200px | | xxl | ≥1400px | |
opacity | Annotated[Number, V.between(0.0, 1.0)] | 1.0 | 定义控件的透明度。 取值范围从 0.0（完全透明）到 1.0（完全不透明，无任何透明感）。 抛出异常： ValueError：如果它不在 0.0 到 1.0（含）之间。 |
tooltip | Optional[TooltipValue] | None | 鼠标悬停在此控件上时显示的工具提示。 |
badge | Optional[BadgeValue] | None | 显示在此控件顶部的徽章。 |
visible | bool | True | 每个控件都有 visible 属性，默认为 True —— 控件会渲染在页面上。将 visible 设为 False 会彻底阻止控件（及其所有子控件，如果有）渲染到页面画布上。隐藏的控件无法通过键盘或鼠标获得焦点或选中，也不会触发任何事件。 |
disabled | bool | False | 每个控件都有 disabled 属性，默认为 False —— 控件及其所有子控件都处于启用状态。 注意： 此属性的值会递归向下传播到所有子控件。 示例： 例如，如果你有一个包含多个输入控件的表单，可以通过禁用容器来一并禁用它们： python ft.Column( disabled = True, controls=[ ft.TextField(), ft.TextField() ] ) |
rtl | bool | False | 控件的文本方向是否为从右到左（RTL）。 |
data | Any | skip_ | 任意类型的自定义数据。 |
key | Optional['KeyValue'] | None | 用于在更新之间保持控件标识稳定的键。 |
只读属性
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
parent | Optional['BaseControl'] | — | 此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。 |
page | 'Page' | — | 此控件所属的页面。 |
事件
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
on_select_all | Optional[ControlEventHandler['DataTable']] | None | 当用户通过标题行中的复选框选中或取消选中所有行时调用。 如果此属性为 None，则会改为相应地调用此表格每个 rows 的 on_select_change 回调。 提示： 要控制某一行是否可选中，请参见 on_select_change。仅当存在可选中行时，此回调才有意义。 |
on_size_change | Optional[EventHandler[LayoutSizeChangeEvent['LayoutControl']]] | None | 当此控件的尺寸发生变化时调用。 size_change_interval 定义此事件的调用频率。 |
on_animation_end | Optional[ControlEventHandler['LayoutControl']] | None | 动画完成时调用。 可用于串联多个动画。 事件处理器参数的 data 属性包含动画名称。 更多信息见此处。 |
方法
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
before_update | — | — | — |
is_isolated | — | — | 返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。 |
init | — | — | 在控件实例初始化之后、首次构建／更新周期之前调用。 重写此钩子以执行依赖于已初始化字段的轻量级设置。不要在此处调用 update()。 |
build | — | — | 在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。 |
before_event | — | — | 在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。 |
did_mount | — | — | 在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。 |
will_unmount | — | — | 在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。 |
get_data_channel | — | — | 解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。 |
update | None | — | 为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。 |
