跳到主要内容

手势检测器 GestureDetector

一个用于检测手势的控件。

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

如果该控件有一个content，它将以该子控件为参考来确定自己的尺寸行为。如果没有content，则它会根据父控件的尺寸自动调整大小。

示例​

在线示例

纸牌游戏教程

可拖动容器​

以下示例演示了如何在 Stack 内自由拖动一个控件。

该示例还展示了 GestureDetector 可以拥有一个子控件（蓝色容器），也可以嵌套在另一个控件内（黄色容器），得到相同的结果。

import flet as ft

def main(page: ft.Page):
    def on_pan_update1(e: ft.DragUpdateEvent):
        c.top = max(0, c.top + e.delta_y)
        c.left = max(0, c.left + e.delta_x)
        c.update()

    def on_pan_update2(e: ft.DragUpdateEvent):
        e.control.top = max(0, e.control.top + e.delta_y)
        e.control.left = max(0, e.control.left + e.delta_x)
        e.control.update()

    gd = ft.GestureDetector(
        mouse_cursor=ft.MouseCursor.MOVE,
        drag_interval=50,
        on_pan_update=on_pan_update1,
    )

    c = ft.Container(gd, bgcolor=ft.colors.AMBER, width=50, height=50, left=0, top=0)

    gd1 = ft.GestureDetector(
        mouse_cursor=ft.MouseCursor.MOVE,
        drag_interval=10,
        on_vertical_drag_update=on_pan_update2,
        left=100,
        top=100,
        content=ft.Container(bgcolor=ft.colors.BLUE, width=50, height=50),
    )

    page.add( ft.Stack([c, gd1], width=1000, height=500))

ft.app(target=main)

属性​

content​

手势检测器包含的子控件。

mouse_cursor​

鼠标指针悬停在控件上时的样式。可能的MouseCursor枚举值有：

  • ALIAS
  • ALL_SCROLL
  • BASIC
  • CELL
  • CLICK
  • CONTEXT_MENU
  • COPY
  • DISAPPEARING
  • FORBIDDEN
  • GRAB
  • GRABBING
  • HELP
  • MOVE
  • NO_DROP
  • NONE
  • PRECISE
  • PROGRESS
  • RESIZE_COLUMN
  • RESIZE_DOWN
  • RESIZE_DOWN_LEFT
  • RESIZE_DOWN_RIGHT
  • RESIZE_LEFT
  • RESIZE_LEFT_RIGHT
  • RESIZE_RIGHT
  • RESIZE_ROW
  • RESIZE_UP
  • RESIZE_UP_DOWN
  • RESIZE_UP_LEFT
  • RESIZE_UP_LEFT_DOWN_RIGHT
  • RESIZE_UP_RIGHT
  • RESIZE_UP_RIGHT_DOWN_LEFT
  • TEXT
  • VERTICAL_TEXT
  • WAIT
  • ZOOM_IN
  • ZOOM_OUT

drag_interval​

水平拖动、垂直拖动和平移更新事件的节流时间间隔（以毫秒为单位）。当用户移动指针时，会生成大量的事件以进行精确跟踪。drag_interval 允许每隔 X 毫秒将拖动更新事件发送给 Flet 程序，从而保持带宽（适用于 Web 和移动应用程序）。默认值为 0，即不进行节流，所有事件都发送给 Flet 程序，实现非常平滑的跟踪。

hover_interval​

on_hover 事件的节流时间间隔（以毫秒为单位）。

事件​

multi_tap_touches​

触发 on_multi_tap 事件所需的最小指针数。

on_double_tap​

用户在同一位置快速连续两次点击屏幕的主要按钮。

on_double_tap_down​

可能引发双击的指针已在特定位置接触屏幕。

在第二次点击的按下事件之后立即触发。

事件处理程序参数是 TapEvent 类的实例。

on_enter​

当鼠标指针进入此控件时触发。

事件处理程序参数是 HoverEvent 类的实例。

on_exit​

当鼠标指针离开此控件时触发。

事件处理程序参数是 HoverEvent 类的实例。

on_horizontal_drag_end​

之前与屏幕接触且水平移动的主要按钮的指针不再与屏幕接触，并且在停止接触屏幕时以特定速度移动。

事件处理程序参数是 DragEndEvent 类的实例，具有以下属性：

  • primary_velocity - 指针在停止接触屏幕时沿主轴方向的速度，单位为逻辑像素每秒。
  • velocity_x - 指针在停止接触屏幕时的 x 轴速度。
  • velocity_y - 指针在停止接触屏幕时的 y 轴速度。

on_horizontal_drag_start​

使用主要按钮触摸屏幕并开始水平移动的指针。

事件处理程序参数是 DragStartEvent 类的实例，具有以下属性：

  • local_x - 指针接触屏幕时的本地位置的 x 分量。
  • local_y - 指针接触屏幕时的本地位置的 y 分量。
  • global_x - 指针接触屏幕时的全局位置的 x 分量。
  • global_y - 指针接触屏幕时的全局位置的 y 分量。
  • timestamp - 触发拖动事件的源指针事件的记录时间戳。

on_horizontal_drag_update​

与主要按钮接触并水平移动的指针已经在水平方向上移动。

事件处理程序参数是 DragUpdateEvent 类的实例，具有以下属性：

  • delta_x - 自上次更新以来，指针在事件接收器的坐标空间中水平移动的量的 x 分量。
  • delta_y - 自上次更新以来，指针在事件接收器的坐标空间中垂直移动的量的 y 分量。
  • local_x - 指针接触屏幕时在事件接收器的坐标系中的本地位置的 x 分量。
  • local_y - 指针接触屏幕时在事件接收器的坐标系中的本地位置的 y 分量。
  • global_x - 触发此更新时指针的全局位置的 x 分量。
  • global_y - 触发此更新时指针的全局位置的 y 分量。
  • primary_delta - 自上次更新以来，指针在事件接收器的坐标空间中沿主轴移动的量。
  • timestamp - 触发拖动事件的源指针事件的记录时间戳。

on_hover​

当鼠标指针进入此控件时触发。

事件处理程序参数是 HoverEvent 类的实例，具有以下属性：

  • local_x - 指针的本地位置的 x 分量。
  • local_y - 指针的本地位置的 y 分量。
  • global_x - 指针的全局位置的 x 分量。
  • global_y - 指针的全局位置的 y 分量。
  • delta_x - 自上次悬停事件以来指针移动的逻辑像素距离的 x 分量。
  • delta_x - 自上次悬停事件以来指针移动的逻辑像素距离的 y 分量。
  • timestamp - 事件的时间戳。

on_long_press_end​

当使用主要按钮触发的长按手势停止接触屏幕时调用。

事件处理程序参数是一个LongPressEndEvent类的实例，具有以下属性：

  • local_x - 指针接触屏幕时的本地位置的x分量。
  • local_y - 指针接触屏幕时的本地位置的y分量。
  • global_x - 指针接触屏幕时的全局位置的x分量。
  • global_y - 指针接触屏幕时的全局位置的y分量。
  • velocity_x - 指针停止接触屏幕时的x分量速度。
  • velocity_y - 指针停止接触屏幕时的y分量速度。

on_long_press_start​

当使用主要按钮触发的长按手势被识别时调用。

当指针在同一位置长时间保持接触屏幕时触发。

事件处理程序参数是一个LongPressStartEvent类的实例，具有以下属性：

  • local_x - 指针接触屏幕时的本地位置的x分量。
  • local_y - 指针接触屏幕时的本地位置的y分量。
  • global_x - 指针接触屏幕时的全局位置的x分量。
  • global_y - 指针接触屏幕时的全局位置的y分量。

on_pan_end​

之前与主要按钮接触屏幕并移动的指针不再接触屏幕，并且在停止接触屏幕时以特定速度移动。

事件处理程序参数是一个DragEndEvent类的实例。

on_pan_start​

使用主要按钮触摸屏幕并开始移动时调用。

事件处理程序参数是一个DragStartEvent类的实例。

on_pan_update​

与主要按钮接触屏幕并移动的指针再次移动时调用。

事件处理程序参数是一个DragUpdateEvent类的实例。

on_scale_end​

事件处理程序参数是一个ScaleEndEvent类的实例，具有以下属性：

  • pointer_count - 手势识别器正在跟踪的指针数量。
  • velocity_x - 最后一个离开屏幕的指针的x分量速度。
  • velocity_y - 最后一个离开屏幕的指针的y分量速度。

on_scale_start​

与屏幕接触的指针已经建立了焦点和初始缩放比例为1.0。

事件处理程序参数是一个ScaleStartEvent类的实例，具有以下属性：

  • focal_point_x - 与屏幕接触的指针的初始焦点的x分量。
  • focal_point_y - 与屏幕接触的指针的初始焦点的y分量。
  • local_focal_point_x - 与屏幕接触的指针的初始焦点的x分量。
  • local_focal_point_y - 与屏幕接触的指针的初始焦点的y分量。
  • pointer_count - 手势识别器正在跟踪的指针数量。

on_scale_update​

事件处理程序参数是一个ScaleUpdateEvent类的实例，具有以下属性：

  • focal_point_x - 与屏幕接触的指针的焦点的x分量。
  • focal_point_y - 与屏幕接触的指针的焦点的y分量。
  • focal_point_delta_x - 与前一次更新相比，手势焦点在事件接收器的坐标空间中移动的x分量。
  • focal_point_delta_y - 与前一次更新相比，手势焦点在事件接收器的坐标空间中移动的y分量。
  • local_focal_point_x - 与屏幕接触的指针的焦点的x分量。
  • local_focal_point_y - 与屏幕接触的指针的焦点的y分量。
  • pointer_count - 手势识别器正在跟踪的指针数量。
  • horizontal_scale - 由与屏幕接触的指针之间在水平轴上的平均距离暗示的缩放比例。
  • vertical_scale - 由与屏幕接触的指针之间在垂直轴上的平均距离暗示的缩放比例。
  • scale - 由与屏幕接触的指针之间的平均距离暗示的缩放比例。

on_secondary_long_press_end​

当使用次要按钮触发的长按手势停止接触屏幕时调用。

事件处理程序参数是一个LongPressEndEvent类的实例。

on_secondary_long_press_start​

当使用次要按钮触发的长按手势被识别时调用。

当指针在同一位置长时间保持接触屏幕时触发。

事件处理程序参数是一个LongPressStartEvent类的实例。

on_secondary_tap​

发生了一个次要按钮的轻触。

on_secondary_tap_down​

可能会触发次要按钮轻触的指针在特定位置接触屏幕时调用。

事件处理程序参数是一个TapEvent类的实例。

on_secondary_tap_up​

将触发次要按钮轻触的指针在特定位置停止接触屏幕时调用。

事件处理程序参数是一个TapEvent类的实例。

on_tap​

发生了一个主要按钮的轻触。

on_tap_down​

可能会触发主要按钮轻触的指针在特定位置接触屏幕时调用。

事件处理程序参数是一个TapEvent类的实例，具有以下属性：

  • local_x - 指针接触屏幕时的本地位置的x分量。
  • local_y - 指针接触屏幕时的本地位置的y分量。
  • global_x - 指针接触屏幕时的全局位置的x分量。
  • global_y - 指针接触屏幕时的全局位置的y分量。
  • kind - 触发事件的设备类型。

on_tap_up​

将触发主要按钮轻触的指针在特定位置停止接触屏幕时调用。

事件处理程序参数是一个TapEvent类的实例。

on_vertical_drag_end​

之前与主要按钮接触屏幕并垂直移动的指针不再接触屏幕，并且在停止接触屏幕时以特定速度移动。

事件处理程序参数是一个DragEndEvent类的实例。

on_vertical_drag_start​

使用主要按钮触摸屏幕并开始垂直移动时调用。

事件处理程序参数是一个DragStartEvent类的实例。

on_vertical_drag_update​

与主要按钮接触屏幕并垂直移动的指针在垂直方向上再次移动时调用。

事件处理程序参数是一个DragUpdateEvent类的实例。

on_multi_long_press​

当识别到具有多个指针的长按手势时调用。

on_multi_tap​

多个指针接触屏幕时触发。

事件处理程序参数是一个MultiTapEvent类的实例，具有以下属性：

  • correct_touches - True表示有multi_tap_touches数量的指针接触屏幕；否则为False。

on_scroll​

on_scroll是一个事件处理程序参数，它是ScrollEvent类的一个实例，具有以下属性：

  • local_x - 指针的本地位置的x分量。
  • local_y - 指针的本地位置的y分量。
  • global_x - 指针的全局位置的x分量。
  • global_y - 指针的全局位置的y分量。
  • scroll_delta_x - 以逻辑像素为单位的水平滚动量。
  • scroll_delta_y - 以逻辑像素为单位的垂直滚动量。