静态资源管理 (Assets)

---

Flet 应用可以同时包含代码和静态资源/资源文件（Assets）。静态资源是在发布时会与你的应用程序一同打包和部署的文件，并可以在运行时进行访问。常见的静态资源类型包括静态数据（例如 JSON 文件）、配置文件、图标、图片、视频等。

为了在引用静态资源时能够使用相对路径，你需要在调用 ft.run() 函数启动应用程序时提供静态资源目录的路径。对应的参数名称为 assets_dir，其默认值为 "assets"。该参数指定了存放本地静态资源的文件夹，它可以是绝对路径，也可以是相对于应用程序入口文件（例如 main.py）的相对路径。

---

示例：展示本地图片

假设你在 main.py 文件的同级目录下有一个名为 assets 的文件夹，该文件夹的子文件夹 images 中包含了一个名为 sample.png 的图片文件：

assets/
    images/
        sample.png
main.py

要在你的应用中显示这张图片，你可以这样做：

import flet as ft

def main(page: ft.Page):
    page.add(
        ft.Image(src="images/sample.png")
    )

ft.run(main, assets_dir="assets")

相同的方法也适用于其他静态资源类型，如字体、Lottie 动画、Rive 文件等。

---

在生产环境中访问静态资源文件

对于 UI 控件（例如 Image），你通常需要传递一个相对于 assets_dir 的相对路径：

ft.Image(src="images/sample.png")

而对于非 UI 类文件操作（例如：读取 JSON、打开打包的 SQLite 数据库、加载机器学习模型等），使用指向静态资源目录的绝对路径往往更加便利。出于这个原因，Flet 在生产环境应用中（使用 flet build 构建的桌面/移动应用，网页端除外）会将环境变量 FLET_ASSETS_DIR 设置为指向你静态资源目录的绝对路径。

你可以像下面的示例一样，使用一个本地开发环境下的回退（Fallback）路径（该示例假设静态资源文件夹名为 "assets"）：

import json
import os
from pathlib import Path

import flet as ft

def get_assets_dir() -> Path:
    default_assets_dir = Path(__file__).parent / "assets"   # 本地运行时的回退路径
    return Path(os.environ.get("FLET_ASSETS_DIR", str(default_assets_dir))).resolve()

def main(page: ft.Page):
    assets_dir = get_assets_dir()

    # 加载一个 JSON 文件
    with (assets_dir / "data" / "some_config.json").open() as f:
        config = json.load(f)

    page.add(ft.Text(f"Loaded profile: {config['profile_name']}"))

ft.run(main, assets_dir="assets")

这为你提供了一种在本地运行和生产环境构建中解析打包文件的一致方式。有关更多详细信息，请参阅 FLET_ASSETS_DIR 指南。