列

一个控件，用于垂直排列其子控件。

要使子控件扩展并填充可用的垂直空间，请设置其 expand 属性。

示例

列间距

Python

import flet as ft

def main(page: ft.Page):
    def items(count):
        items = []
        for i in range(1, count + 1):
            items.append(
                ft.Container(
                    content=ft.Text(value=str(i)),
                    alignment=ft.alignment.center,
                    width=50,
                    height=50,
                    bgcolor=ft.colors.AMBER,
                    border_radius=ft.border_radius.all(5),
                )
            )
        return items

    def spacing_slider_change(e):
        col.spacing = int(e.control.value)
        col.update()

    gap_slider = ft.Slider(
        min=0,
        max=100,
        divisions=10,
        value=0,
        label="{value}",
        width=500,
        on_change=spacing_slider_change,
    )

    col = ft.Column(spacing=0, controls=items(5))

    page.add(ft.Column([ ft.Text("Spacing between items"), gap_slider]), col)

ft.app(target=main)

列换行

Python

import flet as ft

HEIGHT = 400

def main(page: ft.Page):
    def items(count):
        items = []
        for i in range(1, count + 1):
            items.append(
                ft.Container(
                    content=ft.Text(value=str(i)),
                    alignment=ft.alignment.center,
                    width=30,
                    height=30,
                    bgcolor=ft.colors.AMBER,
                    border_radius=ft.border_radius.all(5),
                )
            )
        return items

    def slider_change(e):
        col.height = float(e.control.value)
        col.update()

    width_slider = ft.Slider(
        min=0,
        max=HEIGHT,
        divisions=20,
        value=HEIGHT,
        label="{value}",
        width=500,
        on_change=slider_change,
    )

    col = ft.Column(
        wrap=True,
        spacing=10,
        run_spacing=10,
        controls=items(10),
        height=HEIGHT,
    )

    page.add(
        ft.Column(
            [
                ft.Text(
                    "Change the column height to see how child items wrap onto multiple columns:"
                ),
                width_slider,
            ]
        ),
        ft.Container(content=col, bgcolor=ft.colors.AMBER_100),
    )

ft.app(target=main)

列的垂直对齐方式

Python

import flet as ft

def main(page: ft.Page):
    def items(count):
        items = []
        for i in range(1, count + 1):
            items.append(
                ft.Container(
                    content=ft.Text(value=str(i)),
                    alignment=ft.alignment.center,
                    width=50,
                    height=50,
                    bgcolor=ft.colors.AMBER_500,
                )
            )
        return items

    def column_with_alignment(align: ft.MainAxisAlignment):
        return ft.Column(
            [
                ft.Text(str(align), size=10),
                ft.Container(
                    content=ft.Column(items(3), alignment=align),
                    bgcolor=ft.colors.AMBER_100,
                    height=400,
                ),
            ]
        )

    page.add(
        ft.Row(
            [
                column_with_alignment(ft.MainAxisAlignment.START),
                column_with_alignment(ft.MainAxisAlignment.CENTER),
                column_with_alignment(ft.MainAxisAlignment.END),
                column_with_alignment(ft.MainAxisAlignment.SPACE_BETWEEN),
                column_with_alignment(ft.MainAxisAlignment.SPACE_AROUND),
                column_with_alignment(ft.MainAxisAlignment.SPACE_EVENLY),
            ],
            spacing=30,
            alignment=ft.MainAxisAlignment.START,
        )
    )

ft.app(target=main)

列的水平对齐方式

Python

import flet as ft

def main(page: ft.Page):
    def items(count):
        items = []
        for i in range(1, count + 1):
            items.append(
                ft.Container(
                    content=ft.Text(value=str(i)),
                    alignment=ft.alignment.center,
                    width=50,
                    height=50,
                    bgcolor=ft.colors.AMBER_500,
                )
            )
        return items

    def column_with_horiz_alignment(align: ft.CrossAxisAlignment):
        return ft.Column(
            [
                ft.Text(str(align), size=16),
                ft.Container(
                    content=ft.Column(
                        items(3),
                        alignment=ft.MainAxisAlignment.START,
                        horizontal_alignment=align,
                    ),
                    bgcolor=ft.colors.AMBER_100,
                    width=100,
                ),
            ]
        )

    page.add(
        ft.Row(
            [
                column_with_horiz_alignment(ft.CrossAxisAlignment.START),
                column_with_horiz_alignment(ft.CrossAxisAlignment.CENTER),
                column_with_horiz_alignment(ft.CrossAxisAlignment.END),
            ],
            spacing=30,
            alignment=ft.MainAxisAlignment.START,
        )
    )

ft.app(target=main)

无限滚动列表

以下示例演示了在用户滚动到底部时动态添加列表项，创造无限列表的错觉：

import threading
import flet as ft

class State:
    i = 0

s = State()
sem = threading.Semaphore()

def main(page: ft.Page):
    def on_scroll(e: ft.OnScrollEvent):
        if e.pixels >= e.max_scroll_extent - 100:
            if sem.acquire(blocking=False):
                try:
                    for i in range(0, 10):
                        cl.controls.append(ft.Text(f"Text line {s.i}", key=str(s.i)))
                        s.i += 1
                    cl.update()
                finally:
                    sem.release()

    cl = ft.Column(
        spacing=10,
        height=200,
        width=200,
        scroll=ft.ScrollMode.ALWAYS,
        on_scroll_interval=0,
        on_scroll=on_scroll,
    )
    for i in range(0, 50):
        cl.controls.append(ft.Text(f"Text line {s.i}", key=str(s.i)))
        s.i += 1

    page.add(ft.Container(cl, border=ft.border.all(1)))

ft.app(main)

程序控制滚动列

以下示例演示了各种 scroll_to() 选项，并定义了自定义滚动条主题：

import flet as ft

def main(page: ft.Page):
    page.theme = ft.Theme(
        scrollbar_theme=ft.ScrollbarTheme(
            track_color={
                ft.MaterialState.HOVERED: ft.colors.AMBER,
                ft.MaterialState.DEFAULT: ft.colors.TRANSPARENT,
            },
            track_visibility=True,
            track_border_color=ft.colors.BLUE,
            thumb_visibility=True,
            thumb_color={
                ft.MaterialState.HOVERED: ft.colors.RED,
                ft.MaterialState.DEFAULT: ft.colors.GREY_300,
            },
            thickness=30,
            radius=15,
            main_axis_margin=5,
            cross_axis_margin=10,
            # interactive=False,
        )
    )

    cl = ft.Column(
        spacing=10,
        height=200,
        width=float("inf"),
        scroll=ft.ScrollMode.ALWAYS,
    )
    for i in range(0, 100):
        cl.controls.append(ft.Text(f"Text line {i}", key=str(i)))

    def scroll_to_offset(e):
        cl.scroll_to(offset=100, duration=1000)

    def scroll_to_start(e):
        cl.scroll_to(offset=0, duration=1000)

    def scroll_to_end(e):
        cl.scroll_to(offset=-1, duration=2000, curve=ft.AnimationCurve.EASE_IN_OUT)

    def scroll_to_key(e):
        cl.scroll_to(key="20", duration=1000)

    def scroll_to_delta(e):
        cl.scroll_to(delta=40, duration=200)

    def scroll_to_minus_delta(e):
        cl.scroll_to(delta=-40, duration=200)

    page.add(
        ft.Container(cl, border=ft.border.all(1)),
        ft.ElevatedButton("Scroll to offset 100", on_click=scroll_to_offset),
        ft.Row(
            [
               

 ft.ElevatedButton("Scroll to start", on_click=scroll_to_start),
                ft.ElevatedButton("Scroll to end", on_click=scroll_to_end),
            ]
        ),
        ft.ElevatedButton("Scroll to key '20'", on_click=scroll_to_key),
        ft.Row(
            [
                ft.ElevatedButton("Scroll -40", on_click=scroll_to_minus_delta),
                ft.ElevatedButton("Scroll +40", on_click=scroll_to_delta),
            ]
        ),
    )

ft.app(main)

属性

`alignment`

子控件应如何垂直排列。

属性值为 MainAxisAlignment 枚举。

`auto_scroll`

如果在更新子控件时滚动条应自动移动到末端，则为 True。必须为 False 才能使 scroll_to() 方法正常工作。

`controls`

要显示在列中的控件列表。

`horizontal_alignment`

子控件应如何水平排列。

属性值为 CrossAxisAlignment 枚举。默认值为 START。

`on_scroll_interval`

on_scroll 事件的节流时间，单位为毫秒。默认值为 10。

`rtl`

设置文本方向为从右到左。默认值为 False。

`run_spacing`

当 wrap=True 时，运行之间的间距。默认值为 10。

`scroll`

启用列的垂直滚动以防止其内容溢出。

属性值是可选的 ScrollMode 枚举，默认值为 None。

`spacing`

列中控件之间的间距。默认值为 10 虚拟像素。间距仅在 alignment 设置为 start、end 或 center 时应用。

`tight`

指定应占用多少垂直空间。默认值为 False - 分配所有空间给子控件。

`wrap`

设置为 True 时，如果子控件不适合单列，列将把子控件放入额外的列（运行）中。

方法

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

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

offset 是滚动控件的最小和最大范围之间的绝对值，例如：

products.scroll_to(offset=100, duration=1000)

offset 可以为负值以从滚动控件的末端滚动。例如，要滚动到最末端：

products.scroll_to(offset=-1, duration=1000)

delta 允许相对于当前位置移动滚动。使用正 delta 向前滚动，负 delta 向后滚动。例如，向前滚动 50 像素：

products.scroll_to(delta=50)

key 允许将滚动位置移动到指定 key 的控件。大多数 Flet 控件具有 key 属性，该属性在 Flutter 中转换为“全局键”。key 必须在整个页面/视图中唯一。例如：

import flet as ft

def main(page: ft.Page):
    cl = ft.Column(
        spacing=10,
        height=200,
        width=200,
        scroll=ft.ScrollMode.ALWAYS,
    )
    for i in range(0, 50):
        cl.controls.append(ft.Text(f"Text line {i}", key=str(i)))

    def scroll_to_key(e):
        cl.scroll_to(key="20", duration=1000)

    page.add(
        ft.Container(cl, border=ft.border.all(1)),
        ft.ElevatedButton("Scroll to key '20'", on_click=scroll_to_key),
    )

ft.app(main)

备注

scroll_to() 方法不适用于动态构建其项目的 ListView 和 GridView 控件。

duration 是滚动动画的持续时间，单位为毫秒。默认为 0 - 无动画。

curve 配置动画曲线。属性值为 AnimationCurve 枚举。默认值为 ft.AnimationCurve.EASE。

事件

`on_scroll`

当用户更改滚动位置时触发。

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

扩展子控件

当子控件被放置在列中时，可以通过设置其 expand 属性来使其填充可用空间。每个控件都有一个 expand 属性，该属性可以是布尔值（True - 扩展控件以填充所有可用空间）或整数——一个“扩展因子”，用于指定如何与其他扩展子控件划分自由空间。例如，此代码创建了一个包含一个容器的列，该容器占据所有可用空间，并在底部有一个文本控件作为状态栏：

r = ft.Column([
  ft.Container(expand=True, content=ft.Text("Here is search results")),
  ft.Text("Records found: 10")
])

以下具有数字扩展因子的示例创建了一个包含3个容器的列，其高度分别为 20% (1/5)、60% (3/5) 和 20% (1/5)：

r = ft.Column([
  ft.Container(expand=1, content=ft.Text("Header")),
  ft.Container(expand=3, content=ft.Text("Body")),
  ft.Container(expand=1, content=ft.Text("Footer"))
])

一般来说，子控件的最终高度百分比计算为 expand / sum(all expands) * 100%。

如果需要为列的子控件提供灵活性，使其能够扩展以垂直填充可用空间但不要求其填充可用空间，请将其 expand_loose 属性设置为 True。

示例​

列间距​

列换行​

列的垂直对齐方式​

列的水平对齐方式​

无限滚动列表​

程序控制滚动列​

属性​

alignment​

auto_scroll​

controls​

horizontal_alignment​

on_scroll_interval​

rtl​

run_spacing​

scroll​

spacing​

tight​

wrap​

方法​

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

事件​

on_scroll​

扩展子控件​

示例

列间距

列换行