主题
Draggable 继承自：Control, BaseControl
可以拖动到 DragTarget 的控件。
当可拖拽控件识别到拖拽手势开始时，它会显示 content_feedback 控件，使其跟随用户手指在屏幕上移动。 如果用户在某个 DragTarget 上方松开手指，该目标就有机会完成拖放流程。
示例
python
import flet as ft
def main(page: ft.Page):
def handle_drag_will_accept(e: ft.DragWillAcceptEvent):
e.control.content.border = ft.Border.all(
2,
ft.Colors.BLACK_45 if e.accept else ft.Colors.RED,
)
e.control.update()
def handle_drag_accept(e: ft.DragTargetEvent):
e.control.content.bgcolor = e.src.content.bgcolor
e.control.content.border = None
e.control.update()
def handle_drag_leave(e: ft.DragTargetLeaveEvent):
e.control.content.border = None
e.control.update()
page.add(
ft.SafeArea(
content=ft.Row(
controls=[
ft.Column(
controls=[
ft.Draggable(
group="color",
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.CYAN,
border_radius=5,
),
content_feedback=ft.Container(
width=20,
height=20,
bgcolor=ft.Colors.CYAN,
border_radius=3,
),
),
ft.Draggable(
group="color",
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.YELLOW,
border_radius=5,
),
),
ft.Draggable(
group="color",
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.GREEN,
border_radius=5,
),
),
],
),
ft.Container(width=100),
ft.DragTarget(
group="color",
on_will_accept=handle_drag_will_accept,
on_accept=handle_drag_accept,
on_leave=handle_drag_leave,
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.BLUE_GREY_100,
border_radius=5,
),
),
],
),
)
)
if __name__ == "__main__":
ft.run(main)
python
from dataclasses import dataclass
import flet as ft
@dataclass
@ft.observable
class TargetState:
bgcolor: ft.Colors = ft.Colors.BLUE_GREY_100
is_drag_over: bool = False
@ft.component
def App():
target, _ = ft.use_state(lambda: TargetState())
def on_will_accept(_: ft.DragWillAcceptEvent):
target.is_drag_over = True
def on_accept(e: ft.DragTargetEvent):
target.bgcolor = e.src.data
target.is_drag_over = False
def on_leave(_: ft.DragTargetLeaveEvent):
target.is_drag_over = False
return ft.SafeArea(
content=ft.Row(
controls=[
ft.Column(
controls=[
ft.Draggable(
group="color",
data=ft.Colors.CYAN,
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.CYAN,
border_radius=5,
),
content_feedback=ft.Container(
width=20,
height=20,
bgcolor=ft.Colors.CYAN,
border_radius=3,
),
),
ft.Draggable(
group="color",
data=ft.Colors.YELLOW,
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.YELLOW,
border_radius=5,
),
),
ft.Draggable(
group="color",
data=ft.Colors.GREEN,
content=ft.Container(
width=50,
height=50,
bgcolor=ft.Colors.GREEN,
border_radius=5,
),
),
],
),
ft.Container(width=100),
ft.DragTarget(
group="color",
on_will_accept=on_will_accept,
on_accept=on_accept,
on_leave=on_leave,
content=ft.Container(
width=50,
height=50,
bgcolor=target.bgcolor,
border=(
ft.Border.all(2, ft.Colors.BLACK_45)
if target.is_drag_over
else None
),
border_radius=5,
),
),
],
),
)
def main(page: ft.Page):
page.render(App)
if __name__ == "__main__":
ft.run(main)属性
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
content | Annotated[Control, V.visible_control()] | 必填 | 未处于拖拽状态时显示的控件。 如果正在拖拽，则改为显示 content_when_dragging。 抛出异常： ValueError：如果它不可见。 |
group | str | 'default' | 此可拖拽控件所属的分组。 注意： 要让 DragTarget 接受来自 Draggable 的拖放， 二者必须属于同一个 group。 |
content_when_dragging | Optional[Control] | None | 正在拖拽此可拖拽控件时用于替代 content 显示的控件。 如果设置，该控件会在拖拽操作进行期间从视觉上替代 content，让你可以展示不同的外观或一个「空」占位符。如果为 None，拖拽期间仍显示原来的 content。 |
content_feedback | Optional[Control] | None | 拖拽进行时在指针下方显示的控件。 |
axis | Optional[Axis] | None | 将可拖拽控件的移动限制在特定轴上。 - Axis.HORIZONTAL：只允许水平拖拽。 - Axis.VERTICAL：只允许垂直拖拽。 - None：允许向任意方向拖拽。 |
affinity | Optional[Axis] | None | 指定此控件与其他手势竞争以发起拖拽时所沿的轴。 - 如果为 None，只要识别到按下（tap down）手势就开始拖拽， 与方向无关。 - 如果设为 Axis.HORIZONTAL 或 Axis.VERTICAL，控件仅在手势与指定轴匹配时 才发起拖拽，从而可以在该方向上与其他手势竞争。 |
max_simultaneous_drags | Annotated[Optional[int], V.ge(0)] | None | 指定此可拖拽控件允许的并发拖拽操作数量。 - 0 —— 完全禁用拖拽。 - 1 —— 同一时间只允许一次拖拽。 为获得更好的用户体验，可以给 content_when_dragging 提供一个「空」控件， 以直观地表示条目正在被移动。 - 其他任意正整数 —— 允许相应数量的并发拖拽。 - None —— 不限制并发拖拽数量。 抛出异常： ValueError：如果它不大于或等于 0。 |
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_drag_start | Optional[ControlEventHandler['Draggable']] | None | 当此可拖拽控件开始被拖拽时调用。 |
on_drag_complete | Optional[ControlEventHandler['Draggable']] | None | 当此可拖拽控件被放下并被某个 DragTarget 接受时调用。 |
方法
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
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 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。 |
