GestureDetector 继承自：LayoutControl, AdaptiveControl, Control, BaseControl

用于检测手势的控件。

它会尝试识别与其非 None 回调相对应的手势。

如果此控件有 content，它会将尺寸行为交由该子控件决定；否则它会扩展以适配父级。

示例

纸牌接龙游戏教程

import flet as ft


def main(page: ft.Page):
    page.add(
        ft.SafeArea(
            content=ft.GestureDetector(
                hover_interval=50,
                on_tap=lambda e: print(e),
                on_tap_down=lambda e: print(e),
                on_tap_up=lambda e: print(e),
                on_secondary_tap=lambda e: print(e),
                on_secondary_tap_down=lambda e: print(e),
                on_secondary_tap_up=lambda e: print(e),
                on_long_press_start=lambda e: print(e),
                on_long_press_end=lambda e: print(e),
                on_secondary_long_press_start=lambda e: print(e),
                on_secondary_long_press_end=lambda e: print(e),
                on_double_tap=lambda e: print(e),
                on_double_tap_down=lambda e: print(e),
                on_pan_start=lambda e: print(e),
                on_pan_update=lambda e: print(e),
                on_pan_end=lambda e: print(e),
                on_hover=lambda e: print(e),
                on_enter=lambda e: print(e),
                on_exit=lambda e: print(e),
                content=ft.Container(
                    bgcolor=ft.Colors.GREEN,
                    width=200,
                    height=200,
                ),
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    def handle_pan_update1(e: ft.DragUpdateEvent[ft.GestureDetector]):
        container = e.control.parent
        container.top = max(0.0, container.top + e.local_delta.y)
        container.left = max(0.0, container.left + e.local_delta.x)
        container.update()

    def handle_pan_update2(e: ft.DragUpdateEvent[ft.GestureDetector]):
        e.control.top = max(0.0, e.control.top + e.local_delta.y)
        e.control.left = max(0.0, e.control.left + e.local_delta.x)
        e.control.update()

    page.add(
        ft.SafeArea(
            content=ft.Stack(
                width=1000,
                height=500,
                controls=[
                    ft.Container(
                        bgcolor=ft.Colors.AMBER,
                        width=50,
                        height=50,
                        left=0,
                        top=0,
                        content=ft.GestureDetector(
                            mouse_cursor=ft.MouseCursor.MOVE,
                            drag_interval=10,
                            on_pan_update=handle_pan_update1,
                        ),
                    ),
                    ft.GestureDetector(
                        mouse_cursor=ft.MouseCursor.MOVE,
                        drag_interval=10,
                        on_vertical_drag_update=handle_pan_update2,
                        left=100,
                        top=100,
                        content=ft.Container(
                            bgcolor=ft.Colors.BLUE,
                            width=50,
                            height=50,
                        ),
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

import flet as ft


def main(page: ft.Page):
    def on_pan_update(e: ft.DragUpdateEvent[ft.GestureDetector]):
        page.window.left += e.global_delta.x
        page.window.top += e.global_delta.y

    page.add(
        ft.SafeArea(
            content=ft.Stack(
                width=1000,
                height=500,
                controls=[
                    ft.GestureDetector(
                        mouse_cursor=ft.MouseCursor.MOVE,
                        on_pan_update=on_pan_update,
                        left=200,
                        top=200,
                        content=ft.Container(
                            bgcolor=ft.Colors.PINK,
                            width=50,
                            height=50,
                        ),
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

import random

import flet as ft


def main(page: ft.Page):
    def on_pan_update(event: ft.DragUpdateEvent[ft.GestureDetector]):
        container.top = max(0.0, container.top + event.local_delta.y)
        container.left = max(0.0, container.left + event.local_delta.x)
        container.update()

    gesture_detector = ft.GestureDetector(
        mouse_cursor=ft.MouseCursor.BASIC,
        drag_interval=50,
        on_pan_update=on_pan_update,
    )
    container = ft.Container(
        bgcolor=ft.Colors.AMBER,
        width=150,
        height=150,
        left=0,
        top=0,
        content=gesture_detector,
    )

    def handle_button_click(e: ft.Event[ft.Button]):
        gesture_detector.mouse_cursor = random.choice(list(ft.MouseCursor))
        text.value = f"Mouse Cursor:  {gesture_detector.mouse_cursor}"
        gesture_detector.update()
        text.update()

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Stack(
                        width=1000,
                        height=500,
                        controls=[container],
                    ),
                    ft.Button("Change mouse Cursor", on_click=handle_button_click),
                    text := ft.Text(f"Mouse Cursor:  {gesture_detector.mouse_cursor}"),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

属性

名称	类型	默认值	说明
content	Optional[Control]	None	手势检测器所包含的子控件。
mouse_cursor	Optional[MouseCursor]	None	悬停在此控件上的鼠标指针所使用的光标。
drag_interval	int	0	水平拖拽、垂直拖拽和 pan 更新事件的节流时间（毫秒）。 当用户移动指针时会生成大量事件以进行精确跟踪。drag_interval 允许每隔 X 毫秒才向 Flet 程序发送一次拖拽更新事件，从而节省带宽（Web 和移动应用）。 0 表示不节流：所有事件都会发送到 Flet 程序，跟踪非常平滑。
hover_interval	int	0	on_hover 事件的节流时间（毫秒）。
multi_tap_touches	int	0	触发 on_multi_tap 事件所需的最小指针数量。
exclude_from_semantics	bool	False	此检测器的手势是否应从语义树中排除。 当被包裹的内容已经暴露了合适的语义操作，而你不希望此检测器再添加重复的无障碍播报时，将其设为 True。
trackpad_scroll_causes_scale	bool	False	触控板滚动手势是否应被解释为缩放手势。 启用后，兼容的触控板捏合／滚轮输入可以触发 on_scale_start、on_scale_update 和 on_scale_end。
allowed_devices	Optional[list[PointerDeviceType]]	None	将手势识别限制在指定的指针设备类型。 如果为 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	用于在更新之间保持控件标识稳定的键。
adaptive	Optional[bool]	None	启用平台特定渲染，或从父控件继承自适应能力。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

事件

名称	类型	默认值	说明
on_force_press_start	Optional[EventHandler[ForcePressEvent['GestureDetector']]]	None	当指针按下的力度超过起始压强时调用。
on_force_press_peak	Optional[EventHandler[ForcePressEvent['GestureDetector']]]	None	当指针按下的力度超过峰值压强时调用。
on_force_press_update	Optional[EventHandler[ForcePressEvent['GestureDetector']]]	None	在力度按压开始后的每次更新时调用。
on_force_press_end	Optional[EventHandler[ForcePressEvent['GestureDetector']]]	None	当触发力度按压的指针不再接触屏幕时调用。
on_tap	Optional[EventHandler[TapEvent['GestureDetector']]]	None	发生主键点击时调用。
on_tap_down	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当可能引发主键点击的指针在某个位置接触屏幕时调用。
on_tap_up	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当将触发主键点击的指针在某个位置停止接触屏幕时调用。
on_tap_move	Optional[EventHandler[TapMoveEvent['GestureDetector']]]	None	当触发点击的指针移动时调用。
on_tap_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_tap_down 的指针最终不会构成点击。
on_multi_tap	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当多个指针接触屏幕时调用。
on_multi_long_press	Optional[EventHandler[LongPressEndEvent['GestureDetector']]]	None	当识别到多指长按手势时调用。
on_secondary_tap	Optional[ControlEventHandler['GestureDetector']]	None	发生了副键点击。
on_secondary_tap_down	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当可能引发副键点击的指针在某个位置接触屏幕时调用。
on_secondary_tap_up	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当将触发副键点击的指针在某个位置停止接触屏幕时调用。
on_secondary_tap_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_secondary_tap_down 的指针最终不会构成点击。
on_tertiary_tap_down	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当可能引发第三键点击的指针在某个位置接触屏幕时调用。
on_tertiary_tap_up	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当将触发第三键点击的指针在某个位置停止接触屏幕时调用。
on_tertiary_tap_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_tertiary_tap_down 的指针最终不会构成点击。
on_long_press_down	Optional[EventHandler[LongPressDownEvent['GestureDetector']]]	None	当可能引发主键长按的指针接触屏幕时调用。
on_long_press_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_long_press_down 的指针最终不会构成长按。
on_long_press	Optional[ControlEventHandler['GestureDetector']]	None	当识别到主键长按手势时调用。
on_long_press_start	Optional[EventHandler[LongPressStartEvent['GestureDetector']]]	None	当指针在同一位置长时间保持与屏幕接触时触发。
on_long_press_move_update	Optional[EventHandler[LongPressMoveUpdateEvent['GestureDetector']]]	None	当长按被接受后指针移动时调用。
on_long_press_up	Optional[ControlEventHandler['GestureDetector']]	None	当已触发主键长按的指针不再接触屏幕时调用。
on_long_press_end	Optional[EventHandler[LongPressEndEvent['GestureDetector']]]	None	当已触发主键长按的指针停止接触屏幕时调用。
on_secondary_long_press_down	Optional[EventHandler[LongPressDownEvent['GestureDetector']]]	None	当可能引发副键长按的指针接触屏幕时调用。
on_secondary_long_press_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_secondary_long_press_down 的指针最终不会构成长按。
on_secondary_long_press	Optional[ControlEventHandler['GestureDetector']]	None	当识别到副键长按手势时调用。
on_secondary_long_press_start	Optional[EventHandler[LongPressStartEvent['GestureDetector']]]	None	当指针在同一位置长时间保持与屏幕接触时触发。
on_secondary_long_press_move_update	Optional[EventHandler[LongPressMoveUpdateEvent['GestureDetector']]]	None	当副键长按被接受后指针移动时调用。
on_secondary_long_press_up	Optional[ControlEventHandler['GestureDetector']]	None	当已触发副键长按的指针不再接触屏幕时调用。
on_secondary_long_press_end	Optional[EventHandler[LongPressEndEvent['GestureDetector']]]	None	当已触发副键长按的指针停止接触屏幕时调用。
on_tertiary_long_press_down	Optional[EventHandler[LongPressDownEvent['GestureDetector']]]	None	当可能引发第三键长按的指针接触屏幕时调用。
on_tertiary_long_press_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_tertiary_long_press_down 的指针最终不会构成长按。
on_tertiary_long_press	Optional[ControlEventHandler['GestureDetector']]	None	当识别到第三键长按手势时调用。
on_tertiary_long_press_start	Optional[EventHandler[LongPressStartEvent['GestureDetector']]]	None	当指针在同一位置长时间保持与屏幕接触时触发。
on_tertiary_long_press_move_update	Optional[EventHandler[LongPressMoveUpdateEvent['GestureDetector']]]	None	当第三键长按被接受后指针移动时调用。
on_tertiary_long_press_up	Optional[ControlEventHandler['GestureDetector']]	None	当已触发第三键长按的指针不再接触屏幕时调用。
on_tertiary_long_press_end	Optional[EventHandler[LongPressEndEvent['GestureDetector']]]	None	当已触发第三键长按的指针停止接触屏幕时调用。
on_double_tap	Optional[ControlEventHandler['GestureDetector']]	None	用户在同一位置用主键快速连续点击屏幕两次。
on_double_tap_down	Optional[EventHandler[TapEvent['GestureDetector']]]	None	当可能引发双击的指针在某个位置接触屏幕时调用。 在第二次点击的 down 事件之后立即触发。
on_double_tap_cancel	Optional[ControlEventHandler['GestureDetector']]	None	预期会构成双击的指针序列最终不会构成双击。
on_horizontal_drag_down	Optional[EventHandler[DragDownEvent['GestureDetector']]]	None	当指针接触屏幕并可能开始水平移动时调用。
on_horizontal_drag_start	Optional[EventHandler[DragStartEvent['GestureDetector']]]	None	当指针用主键接触屏幕并开始水平移动时调用。
on_horizontal_drag_update	Optional[EventHandler[DragUpdateEvent['GestureDetector']]]	None	当接触屏幕并水平移动的指针在水平方向上发生移动时调用。
on_horizontal_drag_end	Optional[EventHandler[DragEndEvent['GestureDetector']]]	None	当水平移动的指针不再接触屏幕且以特定速度移动时调用。
on_horizontal_drag_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_horizontal_drag_down 的指针最终不会构成水平拖拽。
on_vertical_drag_down	Optional[EventHandler[DragDownEvent['GestureDetector']]]	None	当指针接触屏幕并可能开始垂直移动时调用。
on_vertical_drag_start	Optional[EventHandler[DragStartEvent['GestureDetector']]]	None	当指针接触屏幕并开始垂直移动时调用。
on_vertical_drag_update	Optional[EventHandler[DragUpdateEvent['GestureDetector']]]	None	垂直移动的指针在垂直方向上发生了移动。
on_vertical_drag_end	Optional[EventHandler[DragEndEvent['GestureDetector']]]	None	当垂直移动的指针不再接触屏幕且以特定速度移动时调用。
on_vertical_drag_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_vertical_drag_down 的指针最终不会构成垂直拖拽。
on_pan_down	Optional[EventHandler[DragDownEvent['GestureDetector']]]	None	当指针接触屏幕并可能开始移动时调用。
on_pan_start	Optional[EventHandler[DragStartEvent['GestureDetector']]]	None	当指针接触屏幕并开始移动时调用。
on_pan_update	Optional[EventHandler[DragUpdateEvent['GestureDetector']]]	None	当接触屏幕并正在移动的指针再次发生移动时调用。
on_pan_end	Optional[EventHandler[DragEndEvent['GestureDetector']]]	None	当指针不再接触屏幕且以特定速度移动时调用。
on_pan_cancel	Optional[ControlEventHandler['GestureDetector']]	None	此前触发 on_pan_down 的指针最终不会构成 pan 手势。
on_right_pan_start	Optional[EventHandler[PointerEvent['GestureDetector']]]	None	指针在按住副键的同时接触屏幕并开始移动。
on_right_pan_update	Optional[EventHandler[PointerEvent['GestureDetector']]]	None	接触屏幕、按住副键并正在移动的指针再次发生移动。
on_right_pan_end	Optional[EventHandler[PointerEvent['GestureDetector']]]	None	按住副键的指针不再接触屏幕且以特定速度移动。
on_scale_start	Optional[EventHandler[ScaleStartEvent['GestureDetector']]]	None	当接触屏幕的指针确立焦点且初始缩放为 1.0 时调用。
on_scale_update	Optional[EventHandler[ScaleUpdateEvent['GestureDetector']]]	None	当活动缩放手势的焦点、缩放因子或旋转发生变化时调用。
on_scale_end	Optional[EventHandler[ScaleEndEvent['GestureDetector']]]	None	当活动的缩放手势结束时调用。
on_hover	Optional[EventHandler[HoverEvent['GestureDetector']]]	None	当鼠标指针进入此控件时调用。
on_enter	Optional[EventHandler[HoverEvent['GestureDetector']]]	None	当鼠标指针进入此控件时调用。
on_exit	Optional[EventHandler[HoverEvent['GestureDetector']]]	None	当鼠标指针离开此控件时调用。
on_scroll	Optional[EventHandler[ScrollEvent['GestureDetector']]]	None	当收到指针滚动事件（例如鼠标滚轮或触控板滚动）时调用。
on_size_change	Optional[EventHandler[LayoutSizeChangeEvent['LayoutControl']]]	None	当此控件的尺寸发生变化时调用。 size_change_interval 定义此事件的调用频率。
on_animation_end	Optional[ControlEventHandler['LayoutControl']]	None	动画完成时调用。 可用于串联多个动画。 事件处理器参数的 data 属性包含动画名称。 更多信息见此处。

方法

名称	类型	默认值	说明
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init	—	—	在控件实例初始化之后、第一次 build / 更新循环之前调用。 重写此钩子以执行依赖于已初始化字段的轻量级设置。不要在此处调用 update()。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update	—	—	每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
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 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。