ReorderableListView 继承自：ListView, LayoutControl, ScrollableControl, AdaptiveControl, Control, BaseControl

一个可滚动、可重新排序的控件列表。

提示： 默认情况下，每个子控件（来自 controls）都可以通过自动创建的拖拽手柄拖动（参见 show_default_drag_handles）。要自定义可拖拽区域，请使用 ReorderableDragHandle 定义你自己的拖拽手柄或区域。

示例：

ft.ReorderableListView(
    controls=[
        ft.ListTile(
            title=ft.Text(f"Item {i}"),
            bgcolor=ft.Colors.BLUE_GREY_300,
        )
        for i in range(1, 6)
    ],
)

示例

import flet as ft


def main(page: ft.Page):
    # the primary color is the color of the reorder handle
    page.theme = page.dark_theme = ft.Theme(
        color_scheme=ft.ColorScheme(primary=ft.Colors.BLUE)
    )

    def handle_reorder(e: ft.OnReorderEvent):
        # Reorder controls list to match the UI change
        e.control.controls.insert(e.new_index, e.control.controls.pop(e.old_index))

    def get_color(i):
        return ft.Colors.ERROR if i % 2 == 0 else ft.Colors.ON_ERROR_CONTAINER

    page.add(
        ft.SafeArea(
            expand=True,
            content=ft.Column(
                [  # horizontal
                    ft.ReorderableListView(
                        expand=True,
                        horizontal=True,
                        on_reorder=handle_reorder,
                        controls=[
                            ft.Container(
                                content=ft.Text(f"Item {i}", color=ft.Colors.BLACK),
                                bgcolor=get_color(i),
                                margin=ft.Margin.symmetric(horizontal=5, vertical=10),
                                width=100,
                                alignment=ft.Alignment.CENTER,
                            )
                            for i in range(10)
                        ],
                    ),
                    # vertical
                    ft.ReorderableListView(
                        expand=True,
                        on_reorder=handle_reorder,
                        controls=[
                            ft.ListTile(
                                title=ft.Text(f"Item {i}", color=ft.Colors.BLACK),
                                leading=ft.Icon(ft.Icons.CHECK, color=ft.Colors.RED),
                                bgcolor=get_color(i),
                            )
                            for i in range(10)
                        ],
                    ),
                ]
            ),
        )
    )


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

属性

名称	类型	默认值	说明
controls	list[Control]	[]	此 ReorderableListView 显示的控件。 注意： 当此列表中的某一项被重新排序时，on_reorder 事件会被触发，但它不会自动重新排列 controls 列表。因此，为了让 controls 列表与 UI 保持同步，请在你的 on_reorder 事件处理器中重新排列该列表。示例见 on_reorder。
anchor	Number	0.0	零滚动偏移量的相对位置。
auto_scroller_velocity_scalar	Optional[Number]	None	每像素超滚距离的速度系数。 它表示速度随超滚距离缩放的方式。自动滚动速度 =（超滚距离）* 速度系数。
header	Optional[Control]	None	显示在 controls 之前的不可重排的头部项。
footer	Optional[Control]	None	显示在 controls 之后的不可重排的尾部项。
show_default_drag_handles	bool	True	是否为每个 controls 项显示默认拖拽手柄。 如果为 True：在桌面平台上，拖拽手柄叠加在每个项尾部边缘的中央；在移动平台上，长按项上的任意位置即可开始拖拽。 默认的桌面拖拽手柄只是一个由 ReorderableDragHandle 包裹的 Icons.DRAG_HANDLE。在移动平台上，整个项都会被 ReorderableDragHandle 包裹。 要自定义拖拽手柄的外观或布局，请用 ReorderableDragHandle 包裹每个 controls 项，或包裹每个项中的某个控件。若要完全掌控拖拽手柄，你可能需要把 show_default_drag_handles 设为 False。 示例： python ft.ReorderableListView( show_default_drag_handles=False, controls=[ ft.ListTile( title=ft.Text(f"Draggable Item {i}", color=ft.Colors.BLACK), leading=ft.ReorderableDragHandle( content=ft.Icon(ft.Icons.DRAG_INDICATOR, color=ft.Colors.RED), mouse_cursor=ft.MouseCursor.GRAB, ), ) for i in range(10) ], )
mouse_cursor	Optional[MouseCursor]	None	鼠标指针进入或悬停在拖拽手柄上时的光标。
horizontal	bool	False	controls 是否应水平排列。
reverse	bool	False	滚动视图是否沿阅读方向滚动。 例如，如果阅读方向是从左到右且 horizontal 为 True，那么当 reverse 为 False 时滚动视图从左向右滚动，当 reverse 为 True 时从右向左滚动。 同样地，如果 horizontal 为 False，那么当 reverse 为 False 时滚动视图从上向下滚动，当 reverse 为 True 时从下向上滚动。
spacing	Number	0	controls 之间分隔线的高度。
item_extent	Optional[Number]	None	用于优化渲染的项的固定高度或宽度（当 horizontal 为 True 时）。 注意： 仅当 build_controls_on_demand 为 True 或 spacing 为 0 时此属性才生效。
first_item_prototype	bool	False	是否将第一个项的尺寸用作所有其他项的“原型”。 如果为 True，它们的 height 或 width 将与第一个项相同。
prototype_item	Optional[Control]	None	用作所有项“原型”的控件，即它们的 height 或 width 将与 prototype_item 相同。 注意： 仅当 build_controls_on_demand 为 True 或 spacing 为 0 时此属性才生效。
divider_thickness	Number	0	如果大于 0，则使用 Divider 作为列表视图项之间的间距。
padding	Optional[PaddingValue]	None	controls 的内缩间距。
clip_behavior	ClipBehavior	ClipBehavior.HARD_EDGE	定义如何裁剪 controls。
semantic_child_count	Optional[int]	None	将贡献语义信息的子项数量。
cache_extent	Optional[Number]	None	视口在可见区域前后各有一段缓存区域，用于缓存用户滚动时即将变得可见的项。 落在该缓存区域中的项即使（还）未在屏幕上可见也会被布局。cache_extent 描述缓存区域在视口前缘之前和后缘之后各延伸多少像素。 视口尝试用子项覆盖的总范围 = 前缘之前的 cache_extent + 主轴范围 + 后缘之后的 cache_extent。 缓存区域还用于在 iOS 上实现隐式无障碍滚动：当无障碍焦点从可见视口中的项移动到缓存区域中的不可见项时，框架会通过（隐式的）滚动操作把该项带入视图。
build_controls_on_demand	bool	True	controls 是否应懒加载/按需构建，即仅在它们即将可见时才构建。 在处理大量控件时尤其有用。
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	用于在更新之间保持控件标识稳定的键。
scroll	Optional[Union[ScrollMode, Scrollbar]]	None	定义此控件的滚动条配置。 可以是 Scrollbar 实例，以便完全控制滚动条外观；也可以是 ScrollMode 值，使用现成的滚动条行为。
auto_scroll	bool	False	内容变化时是否自动将滚动位置移动到末尾。 这样在添加新子控件时以及现有内容就地增长时（例如文本流式写入现有子控件），视图都会保持在末尾。当用户滚动离开末尾时暂停固定，一旦滚回末尾则恢复。 注意： 必须为 False，scroll_to 方法才能生效。
auto_scroll_animation	Optional[AnimationValue]	None	auto_scroll 将视图移动到末尾时使用的动画。 接受 Animation（时长 + 曲线）、以毫秒为单位的 int 时长，或 True。默认为 1 秒的 ease 动画；将时长设为 0 可立即跳转（在跟随快速的逐 token 流式输出时推荐使用，以便视图紧密保持固定）。
scroll_interval	Number	10	on_scroll 事件的节流时间（毫秒）。
adaptive	Optional[bool]	None	启用平台特定渲染，或从父控件继承自适应能力。

只读属性

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

事件

名称	类型	默认值	说明
on_reorder	Optional[EventHandler[OnReorderEvent]]	None	当某个 controls 项被拖到新的位置时调用。 注意： 此事件不会自动重新排列 controls。因此，为了让 controls 列表与 UI 保持同步，请在你的 on_reorder 事件处理器中相应地重新排列它。 示例： python def handle_reorder(e: ft.OnReorderEvent): rlv = e.control moved_item = rlv.controls.pop(e.old_index) # Remove the reordered item from its old position rlv.controls.insert(e.new_index, moved_item) # Insert the reordered item into its new position rlv.update()
on_reorder_start	Optional[EventHandler[OnReorderEvent]]	None	当某个 controls 项开始拖拽时调用。
on_reorder_end	Optional[EventHandler[OnReorderEvent]]	None	当被拖拽的 controls 项被放下时调用。
on_size_change	Optional[EventHandler[LayoutSizeChangeEvent['LayoutControl']]]	None	当此控件的尺寸发生变化时调用。 size_change_interval 定义此事件的调用频率。
on_animation_end	Optional[ControlEventHandler['LayoutControl']]	None	动画完成时调用。 可用于串联多个动画。 事件处理器参数的 data 属性包含动画名称。 更多信息见此处。
on_scroll	Optional[EventHandler[OnScrollEvent]]	None	当用户改变滚动位置时调用。

方法

名称	类型	默认值	说明
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
init	—	—	在控件实例初始化之后、首次构建/更新周期之前调用。 重写此钩子以执行依赖已初始化字段的轻量级设置。不要在此处调用 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 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。
scroll_to	—	—	移动滚动位置。 参数： offset：以像素为单位的绝对滚动目标。负值表示相对于末尾（例如 -1 跳到最末尾）。 delta：以像素为单位的相对滚动变化量。正值向前滚动，负值向后滚动。 scroll_key：要滚动到的目标控件的 key。 duration：滚动动画时长。 curve：滚动动画曲线。 说明： - offset、delta 或 scroll_key 中应且只应提供一个。 - auto_scroll 必须为 False。 - 对动态构建条目的控件（例如 ListView、GridView）此方法无效。 示例： python await products.scroll_to(offset=100, duration=1000) await products.scroll_to(offset=-1, duration=1000) # to the end await products.scroll_to(delta=50) # forward 50px await products.scroll_to(scroll_key="item_20", duration=500)