ft.ListView（列表视图），俗称“大列表”，一个线性排列的可滚动控件列表，它按滚动方向依次显示其子项（按需显示，逐步渲染，提高了速度）。在交叉轴上，子项需要填充整个列表视图。

一、基本用法

在这个例子中，我们创建了一个名为lv的ListView对象，并设置了几个属性：

expand=1：使ListView扩展以填充可用空间。
spacing=10：设置每个子控件之间的间距为10像素。
padding=20：设置ListView内部内容与边界的内边距为20像素。
auto_scroll=False：不自动滚动到最底部；如果设置为True，当添加新的子控件时，视图会自动滚动到底部。

然后，我们通过循环向ListView中添加了100个Text控件作为其子控件。最后，将ListView添加到页面中。代码如下：

import flet as ft

def main(page: ft.Page):
    page.title = "Flet 布局控件：ft.ListView（列表视图）"
    # 创建一个可滚动的ListView，包含100个文本控件
    lv = ft.ListView(expand=1, spacing=10, padding=20, auto_scroll=False)
    for i in range(100):
        lv.controls.append(ft.Text(f"列表 第 {i + 1} 行"))
    page.add(lv)

ft.app(target=main)

二、高级用法

import asyncio
import flet as ft

def example():
    async def auto_scroll(e):
        count = 1
        for i in range(0, 60):
            await asyncio.sleep(1)
            lv.controls.append(ft.Text(f"行 {count}"))
            count += 1
            lv.update()

    lv = ft.ListView(spacing=10, padding=20, auto_scroll=True, height=300)

    count = 1

    for i in range(0, 60):
        lv.controls.append(ft.Text(f"行 {count}"))
        count += 1

    return ft.Column(
        controls=[
            lv,
            ft.OutlinedButton(text="自动滚动", on_click=auto_scroll),
        ]
    )

def main(page:ft.Page):
    page.title = "Flet 布局控件：ft.ListView（列表视图）"
    page.window_width = 600
    page.window_height = 400
    page.window_center()
    page.add(example())
ft.app(target=main)

三、属性

auto_scroll

如果滚动条在子项更新时应自动移动到末尾，则为 True。必须为 False 才能使 scroll_to() 方法起作用。

cache_extent

缓存区域内的项目（在用户滚动时即将变为可见的区域之前或之后的区域）即使不可见也会被布局。 cacheExtent 描述了在前导边缘之前和尾部边缘之后，缓存区域延伸多少像素。

视口将尝试用 cache_extent 在前导边缘之前 + 主轴的尺寸 + 在尾部边缘之后覆盖的总尺寸。

clip_behavior

根据此选项，内容将被裁剪（或不裁剪）。属性值是 ClipBehavior 。默认值为 HARD_EDGE。

ClipBehavior 枚举具有以下值：

NONE（无裁剪）
ANTI_ALIAS（反锯齿）
ANTI_ALIAS_WITH_SAVE_LAYER（带保存图层的反锯齿）
HARD_EDGE（硬边缘）

controls

要在 ListView 内显示的 Control 列表。

divider_thickness

如果大于 0，则使用 Divider 作为 ListView 项之间的间距。

first_item_prototype

如果将第一项的尺寸用作所有其他项的“原型”，则为 True，即它们的高度或宽度将与第一项相同。默认为 False。

horizontal

True 表示水平布局 ListView 项。

item_extent

优化渲染的项的固定高度或宽度（对于水平 ListView）。

on_scroll_interval

on_scroll 事件的节流间隔（以毫秒为单位）。默认值为 10。

padding

要插入子项的空间量。

Padding 是 Padding 类的一个实例。

reverse

定义滚动视图是否以读取方向滚动。默认为 False。

semantic_child_count

将提供语义信息的子项数。

spacing

ListView 项之间的 Divider 的高度。如果未指定，则项之间没有间距。

四、方法

scroll_to(offset, delta, key, duration, curve)

将滚动位置移动到绝对 offset、相对 delta 或跳转到指定 key 的控件。

有关方法详细信息和示例，请参见 Column.scroll_to()。

五、事件

on_scroll

当用户更改滚动位置时触发。事件处理程序参数是 OnScrollEvent 类的一个实例。

OnScrollEvent 类具有以下属性：

event_type（str）- 滚动事件的类型：

start - 控件已开始滚动；
update - 控件已更改其滚动位置；
end - 控件已停止滚动；
user - 用户已更改滚动方向；
over - 控件由于更改将导致其滚动位置超出滚动范围而未更改其滚动位置；

pixels（float）- 当前滚动位置，以逻辑像素表示。
min_scroll_extent（float）- pixels 的最小可用值范围。
max_scroll_extent（float）- pixels 的最大可用值范围。
viewport_dimension（float）- 视口的大小。
scroll_delta（float）- 滚动时滚动的距离，以逻辑像素表示。仅在 update 事件中设置。
direction（str）- 用户滚动的方向：idle、forward、reverse。仅在 event_type="user" 事件中设置。
overscroll（float）- 滚动控件避免滚动的逻辑像素数。仅在 over 事件中设置。
velocity（float）- 当发生超滚时 ScrollPosition 变化的速度。仅在 over 事件中设置。

（汇报完毕，感谢收看！）

前军教程网

中小站长与DIV+CSS网页布局开发技术人员的首选CSS学习平台

Flet 布局控件:ft.ListView(列表视图)，俗称“大列表”