StoragePaths 继承自：Service, BaseControl

提供对设备上常用存储路径的访问。

注意： 它的方法在 Web 模式下不受支持。

与 FLET_APP_STORAGE_* 环境变量的关系

StoragePaths 暴露的是原始的平台目录。预先创建好的 FLET_APP_STORAGE_* 环境变量与之对应：FLET_APP_STORAGE_CACHE = get_application_cache_directory()，FLET_APP_STORAGE_TEMP = get_temporary_directory()，而 FLET_APP_STORAGE_DATA = get_application_support_directory() 下由 flet 拥有的 data 子目录（该目录同时也是应用的当前工作目录）。应用存储优先使用这些 环境变量；当你需要其他平台目录（例如 Documents 或 Downloads）时，再使用 StoragePaths。

示例

import flet as ft


async def main(page: ft.Page):
    storage_paths = ft.StoragePaths()

    items = []
    for label, method in [
        ("Application cache directory", storage_paths.get_application_cache_directory),
        (
            "Application documents directory",
            storage_paths.get_application_documents_directory,
        ),
        (
            "Application support directory",
            storage_paths.get_application_support_directory,
        ),
        ("Downloads directory", storage_paths.get_downloads_directory),
        ("External cache directories", storage_paths.get_external_cache_directories),
        (
            "External storage directories",
            storage_paths.get_external_storage_directories,
        ),
        ("Library directory", storage_paths.get_library_directory),
        ("External storage directory", storage_paths.get_external_storage_directory),
        ("Temporary directory", storage_paths.get_temporary_directory),
        ("Console log filename", storage_paths.get_console_log_filename),
    ]:
        try:
            value = await method()
        except ft.FletUnsupportedPlatformException as e:
            value = f"Not supported: {e}"
        except Exception as e:
            value = f"Error: {e}"
        else:
            if isinstance(value, list):
                value = ", ".join(value)
            elif value is None:
                value = "Unavailable"

        items.append(
            ft.Text(
                spans=[
                    ft.TextSpan(
                        f"{label}: ", style=ft.TextStyle(weight=ft.FontWeight.BOLD)
                    ),
                    ft.TextSpan(value),
                ]
            )
        )

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[ft.Column(items, spacing=5)],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

属性

名称	类型	默认值	说明
data	Any	skip_	任意类型的自定义数据。
key	Optional['KeyValue']	None	用于在更新之间保持控件标识稳定的键。

只读属性

名称	类型	默认值	说明
parent	Optional['BaseControl']	—	此控件的直接祖先（父级）。 默认为 None，只有在此控件被挂载（加入页面树）后才有值。 Page 控件（页面树的根）是个例外 —— 它的 parent 始终为 None。
page	'Page'	—	此控件所属的页面。

方法

名称	类型	默认值	说明
get_application_cache_directory	str	—	返回应用专用缓存目录的路径。 如果该目录不存在，会自动创建。 提示： 在运行中的 Flet 应用里，此路径也会通过 FLET_APP_STORAGE_CACHE 环境变量同步暴露。 返回： 应用可用于放置缓存文件的目录路径。 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。
get_application_documents_directory	str	—	返回用于存放用户生成数据的目录路径。 该目录用于存放应用无法重新创建的数据。 对于非用户生成的数据，可以考虑使用： - get_application_support_directory - get_application_cache_directory - get_external_storage_directory 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。 返回： 应用文档目录的路径。
get_application_support_directory	str	—	返回用于存放应用支持文件的目录路径。 如果该目录不存在，会自动创建。 用它存放不向用户展示的文件。不要用于用户数据文件。 提示： 在运行中的 Flet 应用里，FLET_APP_STORAGE_DATA 环境变量指向此路径下的 data 子目录。 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。 返回： 应用支持目录的路径。
get_downloads_directory	Optional[str]	—	返回下载目录的路径。 返回的目录可能不存在；如有必要，客户端应自行验证并创建它。 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。 返回： 下载目录的路径；如果不可用则返回 None。
get_external_cache_directories	Optional[list[str]]	—	返回外部缓存目录的路径。 这些目录通常位于外部存储（例如 SD 卡）上。 某些设备上可能存在多个目录。 抛出异常： FletUnsupportedPlatformException：如果在 Web 或非 Android 平台上调用。 返回： 外部缓存目录路径的列表；如果不可用则返回 None。
get_external_storage_directories	Optional[list[str]]	—	返回外部存储目录的路径。 这些目录通常位于外部存储（例如 SD 卡）上。 某些设备上可能存在多个目录。 抛出异常： FletUnsupportedPlatformException：如果在 Web 或非 Android 平台上调用。 返回： 外部存储目录路径的列表；如果不可用则返回 None。
get_library_directory	str	—	返回库目录的路径。 该目录用于存放持久的、会被备份且对用户不可见的文件（例如 sqlite.db）。 抛出异常： FletUnsupportedPlatformException：如果在 Web 或非 Apple 平台上调用。 返回： 库目录的路径。
get_external_storage_directory	Optional[str]	—	返回顶层外部存储目录的路径。 抛出异常： FletUnsupportedPlatformException：如果在 Web 或非 Android 平台上调用。 返回： 外部存储目录的路径；如果不可用则返回 None。
get_temporary_directory	str	—	返回临时目录的路径。 该目录不会被备份，适合存放已下载文件的缓存。 其中的文件随时可能被清除。 调用方负责管理此目录中的文件。 提示： 在运行中的 Flet 应用里，此路径也会通过 FLET_APP_STORAGE_TEMP 环境变量同步暴露。 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。 返回： 临时目录的路径。
get_console_log_filename	str	—	返回用于调试的 console.log 文件的路径。 该文件位于 get_application_cache_directory 中。 提示： 在运行中的 Flet 应用里，此路径也会通过 FLET_APP_CONSOLE 环境变量同步暴露。 抛出异常： FletUnsupportedPlatformException：如果在 Web 平台上调用。 返回： 控制台日志文件的路径。
init	—	—	—
is_isolated	—	—	返回此控件是否被标记为隔离。 隔离控件会被排除在父级驱动的更新遍历之外，并需要自行管理更新边界。
build	—	—	在控件初始化期间调用一次，用于定义其子控件。在此方法中 page 属性可用。
before_update	—	—	每当此控件被更新时都会调用此方法。 注意： 务必不要在此处调用或请求 update()。
before_event	—	—	在事件处理器执行之前拦截事件。 返回 False 可取消分发。返回 True 或 None 则继续正常的事件处理。
did_mount	—	—	在控件挂载到页面树之后调用。 重写此方法以启动需要已挂载页面的资源，例如订阅、定时器或服务监听器。
will_unmount	—	—	在控件从页面树移除之前调用。 重写此方法以释放 did_mount() 中创建的资源，例如订阅、定时器或外部句柄。
get_data_channel	—	—	解析为此 widget 在 Dart 侧分配的 [DataChannel]。模式： on_data_channel_open: Optional[ft.EventHandler[DataChannelOpenEvent]] = None def init(self): self.on_data_channel_open = self._on_open def _on_open(self, e): self._channel = self.get_data_channel(e.channel_id) 幂等 —— 底层的 Connection 会按 id 缓存 DataChannel，因此重复调用会返回同一实例。没有错误路径：该 id 始终来自框架触发的事件，所以当此方法运行时，通道在两端都已存在。
update	None	—	为此控件请求一次 UI 更新。 在更改控件状态或属性后调用。控件必须已挂载到页面且未被标记为冻结。