创建一个新的 Flet 应用

你的第一个应用

flet create 会生成一个全新的「极简」Flet 应用，flet run 负责启动它：

uv

uvx --with flet-cli flet create my-app
cd my-app
uv run flet run

pip

# 在已创建并激活虚拟环境、且已安装 Flet 之后（见[安装](installation.md)），从应用目录运行：
flet create .
flet run

无需单独的 install 步骤：uvx 会在一次性环境中运行 Flet CLI，首次 uv run 会从生成的 pyproject.toml 安装新应用的依赖（如果你还没安装 uv，见 安装）。使用 pip 时，在已创建并激活虚拟环境、且已安装 Flet 的前提下从应用目录运行上面的命令即可。

INFO

flet create 会把 README.md 和 pyproject.toml 写入目标目录，并替换任何已存在的同名文件。请在一个全新或空的目录中运行它。

该命令会创建以下目录结构：

my-app/
├── README.md
├── pyproject.toml
├── src/
│   ├── assets/
│   │   └── icon.png
│   └── main.py
└── storage/
    ├── data/
    └── temp/

您可以在这里找到关于 flet create 命令的更多详细信息。

---

自动更新 (Auto-update)

Flet 会在每个事件处理程序和 main() 函数结束时自动调用 page.update()（或在最近的隔离祖先控件上调用 .update()）。这意味着在大多数情况下，您不需要自己调用 .update()：

import flet as ft

def main(page: ft.Page):
    def button_click(e):
        page.controls.append(ft.Text("Clicked!"))
        # 无需调用 page.update() —— 它会自动发生

    page.controls.append(ft.Button("Click me", on_click=button_click))
    # 这里同样无需调用 page.update()

ft.run(main)

注意

如果您的事件处理程序已经显式调用了 .update()（例如为 Flet 0.x 编写的代码），则会跳过自动更新，以避免多余的重复更新。

---

禁用自动更新 (Disabling auto-update)

您可以禁用自动更新，以便对何时向客户端发送更新进行更精细的控制。使用 ft.context.disable_auto_update() 和 ft.context.enable_auto_update() 可以切换此行为。

当在处理程序内部调用时，该设置仅适用于当前的事件处理上下文：

import flet as ft

def main(page: ft.Page):
    def add_many_items(e):
        ft.context.disable_auto_update()
        for i in range(100):
            page.controls.append(ft.Text(f"Item {i}"))
        page.update()  # 仅对这 100 个项目进行一次更新

    page.controls.append(ft.Button("Add items", on_click=add_many_items))

ft.run(main)

当在事件处理程序外部（例如在模块级别）调用时，它控制整个应用的全局默认设置：

import flet as ft

# 全局禁用自动更新
ft.context.disable_auto_update()

def main(page: ft.Page):
    def button_click(e):
        page.controls.append(ft.Text("Clicked!"))
        page.update()  # 由于关闭了自动更新，必须显式调用

    page.controls.append(ft.Button("Click me", on_click=button_click))
    page.update()

ft.run(main)

现在，让我们运行应用程序，看看 Flet 的实际运行效果吧！