 函数深度解析与实战指南)
Flet 应用启动核心flet.run() 函数深度解析与实战指南【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/fletflet.run()是 Flet 框架中启动应用的统一入口无论你的目标是桌面窗口、Web 服务还是移动端嵌入式运行它都能根据参数与环境自动选择合适的传输通道并拉起应用。本指南以仓库 API 文档 run.md 所引用的flet.run为骨架结合其实现源码 app.py逐一拆解每个参数的含义、底层运行机制与环境变量并给出可在当前仓库示例中直接验证的实战用法。一、flet.run 在 Flet 中的定位flet.run()是 Flet 应用的生命周期入口函数。它接收一个以Page为唯一参数的处理器handler在该处理器中你可以构建界面、绑定事件并执行业务逻辑然后由run()负责与 Flet 客户端桌面窗口、浏览器、移动端建立连接、维护会话并驱动界面更新。从源码看run()定义于 sdk/python/packages/flet/src/flet/app.py并通过 sdk/python/packages/flet/src/flet/init.py 以flet.run的名字暴露给用户。值得注意的是Flet 1.0 采用 PEP 562 惰性导入策略见__init__.py头部注释import flet不再立即加载全部约 270 个模块flet.run在首次访问时才被导入因此直接使用ft.run(main)是零额外开销的。最小可用示例仓库示例应用大量采用ft.run(main)这种写法例如 sdk/python/examples/apps/7guis/counter/main.pyimport flet as ft def main(page: ft.Page): page.title Counter # ... 构建界面与事件处理 ... ft.run(main)完整函数签名def run( main: AppCallable, before_main: Optional[AppCallable] None, name: str , host: Optional[str] None, port: int 0, view: Optional[AppView] AppView.FLET_APP, assets_dir: Optional[str] assets, upload_dir: Optional[str] None, web_renderer: WebRenderer WebRenderer.AUTO, route_url_strategy: RouteUrlStrategy RouteUrlStrategy.PATH, no_cdn: Optional[bool] False, export_asgi_app: Optional[bool] False, )其中AppCallable是同步或异步回调的类型别名它接受单个Page参数返回值被忽略见 app.py 中的定义。二、参数逐项详解以下是flet.run()全部参数的说明与源码级解读参数默认值与语义以 app.py 中的 docstring 为准参数类型默认值作用mainAppCallable必填应用入口接收一个Page参数的函数或协程before_mainAppCallableNone在Page创建之后、main执行之前调用namestr应用/页面名称用于 Web 场景下的 URL 路径hoststrNoneWeb 服务器绑定的主机/IPportint0TCP 端口为0时由系统自动选择可用端口viewAppViewAppView.FLET_APP应用呈现模式桌面窗口 / 浏览器等assets_dirstrassets应用资源目录路径upload_dirstrNone上传文件保存目录web_rendererWebRendererWebRenderer.AUTOWeb 渲染器类型route_url_strategyRouteUrlStrategyRouteUrlStrategy.PATHURL 路由策略path或hashno_cdnboolFalse是否不从 CDN 加载 CanvasKit、Pyodide 与字体export_asgi_appboolFalse为True时返回配置好的 ASGI 应用而非运行事件循环回调参数main 与 before_mainmain应用入口。run()内部通过__get_on_session_createdapp.py构造会话回调在该回调中依据处理器类型分派执行if inspect.iscoroutinefunction(main): await main(session.page) elif inspect.isasyncgenfunction(main): async for _ in main(session.page): await session.after_event(session.page) elif inspect.isgeneratorfunction(main): for _ in main(session.page): await session.after_event(session.page) else: main(session.page) # 同步函数 await session.after_event(session.page)也就是说main可以是普通同步函数、协程函数、异步生成器、同步生成器中的任意一种框架都会正确处理并保证在处理器返回后调用session.after_event()刷新页面。若main抛出未捕获异常框架会记录Unhandled error in main() handler日志并通过session.error()上报到客户端。before_main在Page创建后、main执行前运行的钩子常用于注入依赖、初始化会话级状态。name、host、portWeb 服务定位参数name页面名称会拼接到 Web URL 路径中。实际生效值还受环境变量FLET_WEB_APP_PATH影响——当name为空而该环境变量非空时以环境变量为准见__get_page_nameapp.py。hostWeb 服务器绑定地址。源码中url_host 127.0.0.1 if host in [None, , *] else host即默认绑定本机回环地址。port0表示自动分配。在强制 Web 服务器模式下force_web_serverTrue若端口仍为0则使用8000见 app.py。assets_dir 与 upload_dir资源与上传目录assets_dir默认值为常量DEFAULT_ASSETS_DIR assetsapp.py。相对路径会基于当前脚本目录解析为绝对路径export_asgi_appTrue时则基于当前工作目录见__get_assets_dir_path的relative_to_cwd参数app.py。源码还兼容 PyInstaller onefile 打包场景当_MEI in __file__时相对路径基于可执行文件所在目录解析。若默认assets目录不存在框架仅记录 debug 日志不告警若显式指定了不存在的目录则记录assets_dir does not exist警告并将该目录置空。upload_dir同理支持相对路径解析app.py。两者均支持环境变量覆盖FLET_ASSETS_DIR优先级最高且永远不会被静默丢弃。三、呈现模式AppView 枚举view参数控制应用以何种方式呈现。其可选值定义在 sdk/python/packages/flet/src/flet/controls/types.py枚举值字符串值行为AppView.WEB_BROWSERweb_browser以 Web 服务器方式运行并自动在用户浏览器中打开AppView.FLET_APPflet_app在 Flet 桌面窗口中运行默认AppView.FLET_APP_WEBflet_app_web桌面窗口 Web 服务器后端AppView.FLET_APP_HIDDENflet_app_hidden启动隐藏的 Flet 桌面窗口桌面窗口模式的启动依赖flet_desktop包run_async中通过ensure_flet_desktop_package_installed()按需确保安装并调用open_flet_view_async打开窗口见 app.py。四、Web 渲染器与路由策略WebRendererWeb 端渲染器选择web_renderer用于 Web 托管场景定义于 types.pyAUTO默认由运行时自动选择。WebAssembly 构建下 Chromium 系浏览器优先使用 skwasm其他浏览器回退到 CanvasKit默认 Web 构建则始终使用 CanvasKit。CANVAS_KITCanvasKit 渲染器兼容性最好是默认 Web 构建的标准渲染器Flet 每次 UI 更新都会在 JavaScript 与 Dart 之间交换字节缓冲区CanvasKit 在这种交换上显著更快。SKWASM仅 WebAssembly 构建可用渲染性能可能更优但跨 JS/Dart 边界的字节缓冲交换较慢且需要浏览器与服务器满足 WebAssembly 及多线程渲染时SharedArrayBuffer 安全配置要求。RouteUrlStrategyURL 路由策略route_url_strategy仅影响 Web 托管应用定义于 types.pyPATH默认路由存放在浏览器 pathname 中URL 形如https://example.com/store。此策略通常要求 Web 服务器将未匹配的请求重写到index.html以保证深链接与页面刷新可用。HASH路由存放在 URL 锚点片段中URL 形如https://example.com/#/store。当无法配置托管服务器做 pathname 重写时该策略是实用之选。五、底层运行机制四种传输通道的自动选择flet.run()最终调用asyncio.run(run_async(...))app.py。在run_async内部app.py传输通道按以下优先级选择is_pyodide() 且非嵌入式 → PyodideConnection浏览器内嵌执行 FLET_DART_BRIDGE_PORT 且嵌入式 → dart_bridge 进程内传输 嵌入式或 view ∈ {FLET_APP, FLET_APP_HIDDEN, None} 且未强制 Web → Socket 服务器 其余情况 → FastAPI/uvicorn Web 服务器Pyodide 通道在浏览器内直接运行 Pythonis_pyodide()为真时通过PyodideConnection建立连接app.py。dart_bridge 进程内通道嵌入式场景下设置FLET_DART_BRIDGE_PORT时启用app.py。它与 Socket 服务器使用相同的 MsgPack 帧协议但通过进程内字节通道传输省去了 socket 文件与内核上下文切换。从源码注释可见Android 进程复用场景下_DartBridgeServerHandle会通过dart_bridge.add_session_restart_handler监听 Dart VM 重启并透明地在新端口上重建连接。Socket 服务器桌面/嵌入式模式默认通道FletSocketServer支持FLET_SERVER_UDS_PATH环境变量指定 Unix Domain Socketapp.py。Web 服务器基于 FastAPI/uvicorn由flet_web包中的serve_fastapi_web_app提供服务app.py负责加载 Web 前端、处理页面 URL、资源与上传目录。此外run_async为桌面/Web 进程注册了SIGINT与SIGTERM信号处理器收到信号后通过terminate事件请求优雅退出并在finally中确保关闭连接app.py。六、环境变量一览flet.run()/run_async()的行为受以下环境变量影响均可在 app.py 源码中核实环境变量作用FLET_FORCE_WEB_SERVER为真时强制使用 Web 服务器模式等价于viewWEB_BROWSERFLET_SERVER_PORT覆盖 Web 服务器端口FLET_SERVER_IP覆盖 Web 服务器绑定主机FLET_SERVER_UDS_PATHSocket 服务器改用 Unix Domain SocketFLET_WEB_APP_PATH覆盖name参数决定 Web URL 路径段FLET_ASSETS_DIR覆盖assets_dir优先级最高FLET_DISPLAY_URL_PREFIX应用启动时按prefix page_url view打印 URL且不再自动打开浏览器FLET_DART_BRIDGE_PORT嵌入式场景启用进程内 dart_bridge 通道FLET_LOG_LEVEL设置日志级别flet run -v即通过该变量让框架日志输出到控制台其中FLET_FORCE_WEB_SERVER在 Linux 服务器环境is_linux_server()下会被自动置真这是桌面窗口在无显示服务环境下无法启动时的兜底行为app.py。七、run 与 run_async同步与异步入口flet.run()与flet.run_async()是一对孪生入口后者文档位于 run_async.md区别在于run()同步 API内部用asyncio.run()包装run_async适合在脚本__main__块中直接调用也是仓库示例如 7guis、cookbook 等的标准写法。run_async()协程 API须在既有事件循环中await适合集成到异步应用如 FastAPI、异步测试框架中。其参数与run()完全一致但没有export_asgi_app参数。两者都接受字符串形式的枚举参数如viewweb_browser内部通过AppView(...)、WebRenderer(...)、RouteUrlStrategy(...)自动完成类型转换。在既有事件循环中嵌入export_asgi_appexport_asgi_appTrue是run()独有的集成模式此时run()不会启动事件循环而是返回一个配置好的 FastAPI ASGI 应用依赖flet_web包中的get_fastapi_web_app见 app.py。这使 Flet 页面能够直接挂载到用户自己的 FastAPI/ASGI 服务器中与已有的路由、中间件共存。该模式下资源路径基于当前工作目录解析适用于服务器端部署。八、实战模式小结结合仓库示例与源码行为可总结出以下常用模式桌面应用默认ft.run(main)view保持AppView.FLET_APP自动启动 Flet 桌面窗口。浏览器运行ft.run(main, viewft.AppView.WEB_BROWSER)启动 Web 服务器并打开浏览器亦可通过flet runCLI 配合--web等选项达成参见 CLI 文档。无界面服务端设置FLET_FORCE_WEB_SERVER1或使用host0.0.0.0让外部设备可访问多用户场景下建议结合 FastAPI 集成文档 使用export_asgi_appTrue托管。异步应用在协程中await ft.run_async(main, ...)支持async def main(page)乃至异步生成器形式的处理器。Pyodide/嵌入式run()自动检测 Pyodide 环境与FLET_DART_BRIDGE_PORT无需额外代码即可在浏览器内或嵌入式宿主中运行。九、延伸阅读与源码导航API 文档骨架run.md由 CrocoDocs 组件从 docstring 生成生成管线见 tools/crocodocs/src/crocodocs/generate.py核心实现sdk/python/packages/flet/src/flet/app.py枚举类型定义sdk/python/packages/flet/src/flet/controls/types.py异步入口文档run_async.md真实调用示例sdk/python/examples/apps/7guis/counter/main.py入口相关教程running-app.md打包部署参考packaging 相关文档【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址: https://gitcode.com/gh_mirrors/fl/flet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
