容器 Container

容器可以用背景颜色、边框和填充来装饰控件，并通过填充、边距和对齐方式来定位它。

示例

不同背景颜色的容器

Python

import flet as ft


def main(page: ft.Page):
    page.title = "带有背景颜色的容器"

    c1 = ft.Container(
        content=ft.ElevatedButton("容器中的凸起按钮"),
        bgcolor=ft.colors.YELLOW,
        padding=5,
    )

    c2 = ft.Container(
        content=ft.ElevatedButton(
            "容器中的透明度为0.5的凸起按钮", opacity=0.5
        ),
        bgcolor=ft.colors.YELLOW,
        padding=5,
    )

    c3 = ft.Container(
        content=ft.OutlinedButton("容器中的轮廓按钮"),
        bgcolor=ft.colors.YELLOW,
        padding=5,
    )
    page.add(c1, c2, c3)


ft.app(target=main)

可点击的容器

Python

import flet as ft

def main(page: ft.Page):
    page.title = "容器 - 可点击和不可点击"
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    page.add(
        ft.Row(
            [
                ft.Container(
                    content=ft.Text("不可点击"),
                    margin=10,
                    padding=10,
                    alignment=ft.alignment.center,
                    bgcolor=ft.colors.AMBER,
                    width=150,
                    height=150,
                    border_radius=10,
                ),
                ft.Container(
                    content=ft.Text("无墨水的可点击"),
                    margin=10,
                    padding=10,
                    alignment=ft.alignment.center,
                    bgcolor=ft.colors.GREEN_200,
                    width=150,
                    height=150,
                    border_radius=10,
                    on_click=lambda e: print("无墨水的可点击被点击！"),
                ),
                ft.Container(
                    content=ft.Text("带墨水的可点击"),
                    margin=10,
                    padding=10,
                    alignment=ft.alignment.center,
                    bgcolor=ft.colors.CYAN_200,
                    width=150,
                    height=150,
                    border_radius=10,
                    ink=True,
                    on_click=lambda e: print("带墨水的可点击被点击！"),
                ),
                ft.Container(
                    content=ft.Text("透明带墨水的可点击"),
                    margin=10,
                    padding=10,
                    alignment=ft.alignment.center,
                    width=150,
                    height=150,
                    border_radius=10,
                    ink=True,
                    on_click=lambda e: print("透明带墨水的可点击被点击！"),
                ),
            ],
            alignment=ft.MainAxisAlignment.CENTER,
        ),
    )

ft.app(target=main)

属性

`alignment`

将子控件在容器中对齐。

alignment 是 alignment.Alignment 类对象的实例，具有 x 和 y 属性，表示矩形中心的距离。 x=0，y=0 表示矩形的中心。 x=-1，y=-1 表示矩形的左上角，x=1.0，y=1.0 表示矩形的右下角。在 flet.alignment 模块中有预定义的对齐常量：top_left，top_center，top_right，center_left，center，center_right，bottom_left，bottom_center，bottom_right。

例如：

container_1.alignment = alignment.center
container_2.alignment = alignment.top_left
container_3.alignment = alignment.Alignment(-0.5, -0.5)

`animate`

启用容器的“隐式”动画，逐渐在一段时间内改变其值。

animate 属性的值可以是以下类型之一：

bool - True 启用容器动画，使用 linear 曲线和 1000 毫秒的持续时间。
int - 启用容器动画，使用 linear 曲线和指定的毫秒数。
animation.Animation(duration: int, curve: str) - 启用容器动画，使用指定的持续时间和过渡曲线。

例如：

import flet as ft

def main(page: ft.Page):

    c = ft.Container(
        width=200,
        height=200,
        bgcolor="red",
        animate=ft.animation.Animation(1000, "bounceOut"),
    )

    def animate_container(e):
        c.width = 100 if c.width == 200 else 200
        c.height = 100 if c.height == 200 else 200
        c.bgcolor = "blue" if c.bgcolor == "red" else "red"
        c.update()

    page.add(c, ft.ElevatedButton("Animate container", on_click=animate_container))

ft.app(target=main)

`bgcolor`

容器的背景颜色。

颜色值可以是 #ARGB 格式的十六进制值（例如 #FFCC0000），#RGB 格式的十六进制值（例如 #CC0000）或 flet.colors 模块中的命名颜色。

`blend_mode`

应用于容器的 color 或 gradient 背景的混合模式。有关更多详细信息，请参阅 ShaderMask.blend_mode。

`blur`

在容器下应用高斯模糊效果。

此属性的值可以是以下之一：

数字 - 指定水平和垂直 sigma 的相同值，例如 10。
元组 - 指定水平和垂直 sigma 的不同值，例如 (10, 1)。
ft.Blur 的实例 - 允许分别指定水平和垂直 sigma，以及用于滤镜的 tile_mode。tile_mode 是 ft.BlurTileMode 的值，默认为 ft.BlurTileMode.CLAMP。

例如：

ft.Stack(
    [
        ft.Container(
            content=ft.Text("Hello"),
            image_src="https://picsum.photos/100/100",
            width=100,
            height=100,
        ),
        ft.Container(
            width=50,
            height=50,
            blur=10,
            bgcolor="#44CCCC00",
        ),
        ft.Container(
            width=50,
            height=50,
            left=10,
            top=60,
            blur=(0, 10),
        ),
        ft.Container(
            top=10,
            left=60,
            blur=ft.Blur(10, 0, ft.BlurTileMode.MIRROR),
            width=50,
            height=50,
            bgcolor="#44CCCCCC",
            border=ft.border.all(2, ft.colors.BLACK),
        ),
    ]
)

`border`

在背景颜色上绘制的边框。

容器边框的每一边由 border.BorderSide 类的实例描述，具有两个属性：width（数字）和 color（字符串）。border 属性的值是描述矩形的所有 4 条边的 border.Border 类的实例。可用的辅助方法设置边框样式：

border.all(width, color)
border.symmetric(vertical: BorderSide, horizontal: BorderSide)
border.only(left: BorderSide, top: BorderSide, right: BorderSide, bottom: BorderSide)。

例如：

container_1.border = ft.border.all(10, ft.colors.PINK_600)
container_1.border = ft.border.only(bottom=ft.border.BorderSide(1, "black"))

`border_radius`

如果指定，容器的角将按此半径进行圆角处理。border_radius 是 border_radius.BorderRadius 类的实例，具有 4 个属性：top_left，top_right，bottom_left，bottom_right。可以使用构造函数创建对象，其中所有角的值分别设置，也可以使用辅助方法：

border_radius.all(value)
border_radius.horizontal(left: float = 0, right: float = 0)
border_radius.vertical(top: float = 0, bottom: float = 0)
border_radius.only(top_left, top_right, bottom_left, bottom_right)

例如：

container_1.border_radius= ft.border_radius.all(30)

`clip_behavior`

根据此选项，内容将被裁剪（或不被裁剪）。

属性值为 ClipBehavior 枚举，支持以下值：

NONE
ANTI_ALIAS
ANTI_ALIAS_WITH_SAVE_LAYER
HARD_EDGE

如果 border_radius 不是 None，则默认为 ANTI_ALIAS；否则默认为 HARD_EDGE。

`content`

容器中包含的子控件。

`gradient`

配置渐变背景。值必须是以下类的实例之一：

LinearGradient
RadialGradient
SweepGradient

`LinearGradient`

Container(
    gradient=ft.LinearGradient(
        begin=ft.alignment.top_center,
        end=ft.alignment.bottom_center,
       colors=[ft.colors.BLUE, ft.colors.YELLOW],
    ),
    width=150,
    height=150,
    border_radius=5,
)

LinearGradient 类具有以下属性：

begin - Alignment 类的实例。放置渐变的位置 0.0 的偏移量。
end - Alignment 类的实例。放置渐变的位置 1.0 的偏移量。
colors - 渐变在每个停止点应该获取的颜色。如果 stops 不为空，则此列表必须具有与 stops 相同的长度。此列表必须至少有两种颜色（否则，它不是渐变！）。
stops - 0.0 到 1.0 之间的值列表，表示渐变沿着渐变的分数。如果不为空，则此列表必须具有与 colors 相同的长度。如果第一个值不是 0.0，则隐含一个位置为 0.0 且颜色等于 colors 中的第一个颜色的停止。如果最后一个值不是 1.0，则隐含一个位置为 1.0 且颜色等于 colors 中的最后一个颜色的停止。
tile_mode - 渐变应该如何在 begin 和 end 之前的区域之外的平面上平铺。值是 GradientTileMode 枚举，支持的值为：CLAMP（默认）、DECAL、MIRROR、REPEATED。更多信息在这里。
rotation - 渐变的旋转，以弧度为单位，围绕其边界框的中心点。

更多信息：

线性渐变在 Flutter 文档中。
弧度测量单位在维基百科上。

`RadialGradient`

Container(
    gradient=ft.RadialGradient(
       colors=[ft.colors.YELLOW, ft.colors.BLUE],
    ),
    width=150,
    height=150,
    border_radius=5,
)

RadialGradient 类具有以下属性：

colors、stops、tile_mode、rotation - 参见线性渐变中这些属性的描述。
center - Alignment 类的实例。渐变的中心，作为(-1.0, -1.0) x (1.0, 1.0)方形描述的渐变将映射到的绘画框的偏移量。例如，(0.0, 0.0) 的对齐将在框的中心放置径向渐变。
radius - 渐变的半径，作为绘画框的最短边的分数。例如，如果将径向渐变绘制在宽度为 100.0 像素，高度为 200.0 像素的框上，则半径为 1.0 将在距 center 100.0 像素处放置 1.0 停止。
focal - 渐变的焦点。如果指定，渐变将沿着从 center 到焦点的向量聚焦。
focal_radius - 渐变焦点的半径，作为绘画框的最短边的分数。例如，如果将径向渐变绘制在宽度为 100.0 像素，高度为 200.0 像素的框上，则半径为 1.0 将在距焦点 100.0 像素处放置 1.0 停止。

更多信息：

径向渐变在 Flutter 文档中。

`SweepGradient`

Container(
    gradient=SweepGradient(
        center=ft.alignment.center,
        start_angle=0.0,
        end_angle=math.pi * 2,
       colors=[ft.colors.YELLOW, ft.colors.BLUE],
    ),
    width=150,
    height=150,
    border_radius=5,
)

SweepGradient 类具有以下属性：

colors、stops、tile_mode、rotation - 参见线性渐变中这些属性的描述。
center - 渐变的中心，作为(-1.0, -1.0) x (1.0, 1.0)方形描述的渐变将映射到的绘画框的偏移量。例如，(0.0, 0.0) 的对齐将在框的中心放置梯度。
start_angle - 放置渐变的位置 0.0 的角度（以弧度为单位）。默认为 0.0。
end_angle - 放置渐变的位置 1.0 的角度（以弧度为单位）。默认为 math.pi * 2。

更

多信息：

扫描渐变在 Flutter 文档中。

`image_fit`

查看 Image.fit 以获取更多细节。

`image_opacity`

在与背景混合时设置图像不透明度：值介于 0.0 和 1.0 之间。

`image_repeat`

查看 Image.repeat 以获取更多细节。

`image_src`

将图像设置为容器背景。查看 Image.src 以获取更多细节。

`image_src_base64`

将编码为 Base-64 字符串的图像设置为容器背景。查看 Image.src_base64 以获取更多细节。

`ink`

设置为 True 时，用户单击容器时会产生墨水涟漪效果。默认为 False。

`margin`

围绕装饰和子控件的空白空间。

Margin 是 margin.Margin 类的实例，具有设置矩形所有边的边距的属性：left、top、right、bottom。可以通过构造函数为特定边创建带有值的 margin.Margin 实例，或使用辅助方法创建：

margin.all(value)
margin.symmetric(vertical, horizontal)
margin.only(left, top, right, bottom)

例如：

container_1.margin = margin.all(10)
container_2.margin = 20 # 与 margin.all(20) 相同
container_3.margin = margin.symmetric(vertical=10)
container_4.margin = margin.only(left=10)

`padding`

容器装饰（背景、边框）内部的空白空间。子控件放置在此填充区域内。

padding 是 padding.Padding 类的实例，具有设置矩形的所有边缘填充的属性：left、top、right、bottom。可以通过构造函数创建 padding.Padding 的实例，设置特定边缘的值，也可以使用辅助方法创建：

padding.all(value: float)
padding.symmetric(vertical, horizontal)
padding.only(left, top, right, bottom)

例如：

container_1.padding = ft.padding.all(10)
container_2.padding = 20 # 与 ft.padding.all(20) 相同
container_3.padding = ft.padding.symmetric(horizontal=10)
container_4.padding=padding.only(left=10)

`shadow`

容器投射的阴影列表。

此属性的值是 ft.BoxShadow 类的单个实例或列表，具有以下属性：

spread_radius - 在应用模糊之前，应该膨胀的盒子的量。默认值为 0.0。
blur_radius - 与阴影形状卷积的高斯的标准差。默认值为 0.0。
color - 阴影绘制的颜色。
offset - ft.Offset 类的实例 - 阴影相对于投射元素的位移。正的 x/y 偏移将阴影向右和向下移动，负的偏移将阴影向左和向上移动。偏移量是相对于投射它的元素的位置。默认值为 ft.Offset(0,0)。
blur_style - 此阴影使用的 ft.BlurStyle。默认为 ft.BlurStyle.NORMAL。

示例：

ft.Container(
    border_radius=10,
    width=100,
    height=100,
    shadow=ft.BoxShadow(
        spread_radius=1,
        blur_radius=15,
        color=ft.colors.BLUE_GREY_300,
        offset=ft.Offset(0, 0),
        blur_style=ft.ShadowBlurStyle.OUTER,
    )
)

`shape`

设置容器的形状。值为 BoxShape 枚举：

RECTANGLE（默认）
CIRCLE

`theme_mode`

设置 theme_mode (ft.ThemeMode) 将"重置"父级主题，并为容器内的所有控件创建一个新的、唯一的主题方案。否则，容器的 theme 属性中定义的样式将覆盖父级继承的主题中的相应样式。

`theme`

允许为容器内部和树下的所有控件设置嵌套的 ft.Theme，例如：

import flet as ft

def main(page: ft.Page):
    # 黄色页面主题，使用 SYSTEM（默认）模式
    page.theme = ft.Theme(
        color_scheme_seed=ft.colors.YELLOW,
    )

    page.add(
        # 页面主题
        ft.Container(
            content=ft.ElevatedButton("页面主题按钮"),
            bgcolor=ft.colors.SURFACE_VARIANT,
            padding=20,
            width=300,
        ),

        # 继承主题，覆盖主色
        ft.Container(
            theme=ft.Theme(color_scheme=ft.ColorScheme(primary=ft.colors.PINK)),
            content=ft.ElevatedButton("继承主题按钮"),
            bgcolor=ft.colors.SURFACE_VARIANT,
            padding=20,
            width=300,
        ),
        
        # 唯一的 DARK 主题
        ft.Container(
            theme=ft.Theme(color_scheme_seed=ft.colors.INDIGO),
            theme_mode=ft.ThemeMode.DARK,
            content=ft.ElevatedButton("唯一主题按钮"),
            bgcolor=ft.colors.SURFACE_VARIANT,
            padding=20,
            width=300,
        ),
    )

ft.app(main)

`url`

点击容器时要打开的 URL。如果注册了 on_click 事件，在此之后会触发该事件。

`url_target`

在 Web 模式下打开 URL 的位置：

_blank（默认） - 新标签页/窗口。
_self - 当前标签页/窗口。

事件

`on_click`

当用户点击容器时触发。事件对象 e 是 ContainerTapEvent 类的实例：

class ft.ContainerTapEvent():
    local_x: float
    local_y: float
    global_x: float
    global_y: float

信息

如果 ink 为 True，则 e 将是空的 ControlEvent，而不是 ContainerTapEvent。

一个简单的使用示例：

import flet as ft

def main(page: ft.Page):
    page.vertical_alignment = ft.MainAxisAlignment.CENTER
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    t = ft.Text()

    def container_click(e: ft.ContainerTapEvent):
        t.value = f"local_x: {e.local_x}\nlocal_y: {e.local_y}\nglobal_x: {e.global_x}\nglobal_y: {e.global_y}"
        t.update()

    page.add(
        ft.Column(
            [
                ft.Container(
                    content=ft.Text("容器内可点击"),
                    alignment=ft.alignment.center,
                    bgcolor=ft.colors.GREEN_200,
                    width=200,
                    height=200,
                    border_radius=10,
                    on_click=container_click,
                ),
                t,
            ],
            horizontal_alignment=ft.CrossAxisAlignment.CENTER,
        ),
    )

ft.app(target=main)

`on_hover`

当鼠标指针进入或离开容器区域时触发。事件对象的 data 属性包含鼠标进入时为 true（字符串），离开时为 false。

一个简单的示例，容器在鼠标悬停时更改背景颜色：

import flet as ft

def main(page: ft.Page):
    def on_hover(e):
        e.control.bgcolor = "blue" if e.data == "true" else "red"
        e.control.update()

    page.add(
        ft.Container(width=100, height=100, bgcolor="red", ink=False, on_hover=on_hover)
    )

ft.app(target=main)

`on_long_press`

当长按容器时触发。

示例​

不同背景颜色的容器​

可点击的容器​

属性​

alignment​

animate​

bgcolor​

blend_mode​

blur​

border​

border_radius​

clip_behavior​

content​

gradient​

LinearGradient​

RadialGradient​

SweepGradient​

image_fit​

image_opacity​

image_repeat​

image_src​

image_src_base64​

ink​

margin​

padding​

shadow​

shape​

theme_mode​

theme​

url​

url_target​

事件​

on_click​

on_hover​

on_long_press​

示例