Flet FilePicker 完整指南:文件选择、保存与上传的跨平台实战

原创2026-09-22 11:21:511,888 阅读
文章标签:前端跨平台UI组件桌面应用移动开发Web框架

Flet FilePicker 完整指南:文件选择、保存与上传的跨平台实战

本指南以 Flet 官方文档中的 FilePicker 服务为核心,系统讲解如何在 Python 应用中调用原生文件选择器完成文件选取、目录选择、保存与上传,并结合仓库源码深入解析参数语义与底层实现。读完本文,你将掌握 FilePicker 三个核心方法的完整用法、Web 端浏览器手势限制的解决方案(客户端动作 PickFiles),以及基于 get_upload_url() 与 upload_dir 的内置上传存储实战方案。

FilePicker 是什么

FilePicker 是 Flet 提供的一个服务型控件(Service),它调用操作系统或浏览器的原生文件对话框,让你在桌面、移动和 Web 应用中统一实现三类操作:选择文件(pick_files)、保存文件(save_file)和选择目录(get_directory_path)。

在仓库源码中,该控件的完整实现位于 file_picker.py,类定义为:

@control("FilePicker")
class FilePicker(Service):

该类与 FilePickerFile、FilePickerFileType、FilePickerResultEvent、FilePickerUploadEvent、FilePickerUploadFile 以及客户端动作 PickFiles 一同导出(见 file_picker.py),构成了完整的文件处理 API 家族。

一个值得注意的平台限制:在 Linux 桌面端,该控件依赖 Zenity 提供原生对话框。源码 docstring 中明确说明,在 Ubuntu/Debian 上需执行:

sudo apt-get install zenity

而在浏览器(Web)模式下运行则无需 Zenity。

快速开始:创建实例与三大核心方法

创建 FilePicker 实例非常简单:

import flet as ft

file_picker = ft.FilePicker()

创建之后,根据使用场景调用以下三个方法之一:

  • pick_files():打开文件选择对话框,选择一个或多个文件;
  • save_file():打开保存对话框,让用户选择文件保存路径和文件名;
  • get_directory_path():打开目录选择对话框,返回目录绝对路径。

大多数场景下可以直接用 lambda 表达式绑定到按钮点击事件:

ft.Button(
    content="Pick files",
    on_click=lambda e: file_picker.pick_files(allow_multiple=True)
)

官方示例 pick_save_and_get_directory_path/main.py 展示了三个方法在 async 事件处理器中的标准用法,其中 Web 模式下会禁用「Save file」和「Open directory」按钮(因为这两个操作在浏览器中有平台限制,详见下文):

async def handle_pick_files(e: ft.Event[ft.Button]):
    files = await ft.FilePicker().pick_files(allow_multiple=True)
    selected_files.value = (
        ", ".join(map(lambda f: f.name, files)) if files else "Cancelled!"
    )

async def handle_save_file(e: ft.Event[ft.Button]):
    save_file_path.value = await ft.FilePicker().save_file()

async def handle_get_directory_path(e: ft.Event[ft.Button]):
    directory_path.value = await ft.FilePicker().get_directory_path()

运行效果如下(左侧为三个功能按钮,右侧为操作系统弹出的原生文件对话框):

pick_save_and_get_directory_path 示例运行界面

pick_files():选择文件

源码定义于 file_picker.py,签名如下:

async def pick_files(
    self,
    dialog_title: Optional[str] = None,
    initial_directory: Optional[str] = None,
    file_type: FilePickerFileType = FilePickerFileType.ANY,
    allowed_extensions: Optional[list[str]] = None,
    allow_multiple: bool = False,
    with_data: bool = False,
    compression_quality: int = 0,
    cancel_upload_on_window_blur: bool = True,
) -> list[FilePickerFile]:

参数说明:

参数 默认值 说明
dialog_title None 对话框标题
initial_directory None 对话框打开时的初始目录
file_type ANY 允许选择的文件类型(见下方枚举)
allowed_extensions None 自定义允许的扩展名列表,仅当 file_type 为 CUSTOM 时生效
allow_multiple False 是否允许一次选择多个文件
with_data False 是否将文件内容读入 FilePickerFile.bytes
compression_quality 0 图片压缩质量,取值 0~100,0 表示不压缩
cancel_upload_on_window_blur True 仅 Web 端有效:是否将浏览器窗口失焦视为取消选择。网络较慢或设备较慢时建议设为 False 以避免误丢有效选择

file_type 参数使用 FilePickerFileType 枚举(见 file_picker.py),包含 ANY(任意类型)、MEDIA(视频+图片)、IMAGE(仅图片)、VIDEO(仅视频)、AUDIO(仅音频)和 CUSTOM(仅 allowed_extensions 中列出的自定义扩展名)。

源码中还包含参数校验逻辑:当 compression_quality 不在 0~100 区间内时,会抛出 ValueError(见 file_picker.py)。

调用后返回 list<a href="https://link.gitcode.com/i/cbadedee389fc8dcb8387ce66434e38a" target="_blank">FilePickerFile]。FilePickerFile 是文件元数据的数据类(见 [file_picker.py):

  • id:当前选择范围内由 Flet 分配的文件标识,上传时优先用于匹配;
  • name:文件名(不含目录路径);
  • size:文件大小(字节);
  • path:文件的绝对路径,Web 模式始终为 None,原生平台也可能因系统选择器不暴露路径而为 None;
  • bytes:文件内容,仅当调用 pick_files(with_data=True) 时才会返回,否则为 None。

save_file():保存文件

源码定义于 file_picker.py:

async def save_file(
    self,
    dialog_title: Optional[str] = None,
    file_name: Optional[str] = None,
    initial_directory: Optional[str] = None,
    file_type: FilePickerFileType = FilePickerFileType.ANY,
    allowed_extensions: Optional[list[str]] = None,
    src_bytes: Optional[bytes] = None,
) -> Optional[str]:

参数说明:

参数 默认值 说明
dialog_title None 对话框标题
file_name None 默认文件名
initial_directory None 对话框打开的初始目录
file_type ANY 允许选择的文件类型
allowed_extensions None 允许的扩展名,仅当 file_type 为 CUSTOM 时生效
src_bytes None 要写入的文件内容字节。在 Web、iOS、Android 模式下必填

返回值:保存成功返回文件路径;用户取消返回 None。

关键平台差异在源码中通过校验逻辑体现(见 file_picker.py):

  • 在 Web、iOS、Android 模式下,必须提供 src_bytes,否则抛出 ValueError(这些平台没有可写的文件系统路径,Flet 会将字节内容交给客户端执行下载/写入);
  • 在 Web 模式下还必须提供 file_name,否则同样抛出 ValueError。

get_directory_path():选择目录

源码定义于 file_picker.py:

async def get_directory_path(
    self,
    dialog_title: Optional[str] = None,
    initial_directory: Optional[str] = None,
) -> Optional[str]:

参数仅有 dialog_title(对话框标题,默认 FilePicker)和 initial_directory(初始目录)。返回所选目录的绝对路径,取消时返回 None。

该方法不支持 Web 模式:源码开头即检查 self.page.web,若在 Web 模式调用会抛出 FletUnsupportedPlatformException(见 file_picker.py),错误信息为 "get_directory_path is not supported in web mode"。这也是官方示例中在 Web 模式禁用「Open directory」按钮的原因。

Web 应用中的手势限制与 PickFiles 客户端动作

官方文档特别标注了一个重要的 Web 平台警告:浏览器只会在处理点击或按键事件期间打开文件选择器。如果从 on_click 处理器中调用 pick_files(),点击事件要先传到你的 Python 代码、指令再传回客户端,此时浏览器认为手势已结束、权限已失效——Safari 会静默拒绝,而 Chrome 和 Firefox 则允许,于是同一个应用往往在除 iPhone/iPad 之外的平台上都能正常工作。

解决方案是把选择动作附加到控件上,而不是从事件处理器中调用。Flet 为此提供了客户端动作 PickFiles(ClientAction),它由客户端在原始手势内部直接打开对话框,选中的文件通过 FilePicker.on_result 事件返回。源码中对它的注释写得很清楚(见 file_picker.py):

Equivalent to FilePicker.pick_files, but performed by the client inside the user's gesture, which is the only time a browser opens a file picker. This is what makes file picking work in a web app on iOS.

PickFiles 的动作字段与 pick_files() 参数一一对应(dialog_title、initial_directory、file_type、allowed_extensions、allow_multiple、with_data、compression_quality、cancel_upload_on_window_blur),并在 __post_init__ 中绑定到指定的 FilePicker(见 file_picker.py)。

官方完整示例见 pick_files_action/main.py,核心结构为:

def handle_result(e: ft.FilePickerResultEvent):
    # PickFiles 动作在 Python 看到点击之前就打开了对话框,
    # 因此选择结果不是返回值,而是到达 on_result 事件。
    state.picked_files = e.files
    ...

file_picker = ft.FilePicker(
    on_result=handle_result,
    on_upload=handle_upload_progress,
)
page.services.append(file_picker)

page.add(
    ft.SafeArea(
        content=ft.Column(
            controls=[
                ft.Button(
                    content="Select files...",
                    icon=ft.Icons.FOLDER_OPEN,
                    # 将动作附加到控件上,而不是在 on_click 中调用
                    # file_picker.pick_files(),这是让对话框在 iOS 上打开的关键
                    action=ft.PickFiles(file_picker, allow_multiple=True),
                ),
                ...
            ],
        ),
    )
)

运行该 Web 示例的命令(需先设置密钥):

export FLET_SECRET_KEY=<some_secret_key>
uv run flet run --web examples/services/file_picker/pick_files_action/main.py

需要理解的两点关键差异:

  1. 结果流向不同:pick_files() 直接返回文件列表;而 PickFiles 动作的结果通过 on_result 事件到达——源码中 FilePickerResultEvent 的 docstring 明确注明它"由 PickFiles 动作触发,不由 pick_files() 触发"(见 file_picker.py)。
  2. 文件仍与 FilePicker 关联:选中文件依然与该 FilePicker 实例关联,因此后续调用 upload() 的方式与 pick_files() 之后完全相同。

更完整的「客户端动作」机制说明可参阅 Client actions,其中还提到动作会先执行、随后 on_click 处理器照常被调用,且一个控件可以同时接受单个动作或动作列表。

上传文件:upload() 与上传进度

要上传一个或多个文件,先调用 FilePicker.pick_files() 让用户选择文件,再把返回的文件列表传给 FilePicker.upload() 执行上传。

upload() 的源码定义于 file_picker.py:

async def upload(self, files: list[FilePickerUploadFile]):

上传描述符 FilePickerUploadFile(见 file_picker.py)包含以下字段:

字段 默认值 说明
upload_url 必填 上传目标 URL,可以是绝对 URL,也可以是 page.get_upload_url() 返回的页面相对 URL
method "PUT" 上传请求使用的 HTTP 方法,通常为 PUT 或 POST
id None 所选文件的标识(来自 pick_files()),优先用于匹配文件
name None 文件名,作为 id 缺失或匹配失败时的回退匹配键

上传过程中的进度通过 on_upload 事件回调报告。源码 docstring 说明了其触发规律(见 file_picker.py):每个文件至少触发两次——上传开始前 progress 为 0.0,上传完成时为 1.0;超过 1 MB 的文件还会每增加 10% 触发一次额外进度事件(如 0.1、0.2……)。事件对象 FilePickerUploadEvent(见 file_picker.py)包含 file_name、progress(0.0~1.0)和可选的 error 字段。

官方示例 pick_and_upload/main.py 演示了用 ProgressRing 展示每个文件上传进度的完整流程:

def on_upload_progress(e: ft.FilePickerUploadEvent):
    prog_bars[e.file_name].value = e.progress

async def handle_files_pick(e: ft.Event[ft.Button]):
    state.file_picker = ft.FilePicker(on_upload=on_upload_progress)
    files = await state.file_picker.pick_files(allow_multiple=True)
    state.picked_files = files
    ...

async def handle_file_upload(e: ft.Event[ft.Button]):
    await state.file_picker.upload(
        files=[
            ft.FilePickerUploadFile(
                name=file.name,
                upload_url=page.get_upload_url(f"dir/{file.name}", 60),
            )
            for file in state.picked_files
        ]
    )

该示例仅支持 Web 模式运行(非 Web 环境会显示提示文本),运行命令:

export FLET_SECRET_KEY=<some_secret_key>
uv run flet run --web examples/services/file_picker/pick_and_upload/main.py

界面效果如下(选择文件后逐个显示进度环,再点击 Upload 上传):

pick_and_upload 示例运行界面

上传存储:get_upload_url() 与 upload_dir

注意上例中 page.get_upload_url() 的用法——它为 Flet 的内置上传存储生成预签名(presigned)上传 URL。

get_upload_url() 在 page.py 中定义,签名如下:

def get_upload_url(self, file_name: str, expires: int) -> str:
  • file_name:相对于上传存储的路径;
  • expires:URL 的有效期(秒)。

例如:

upload_url = page.get_upload_url("dir/filename.ext", 60)

按用户隔离上传目录

如果需要为每个用户隔离上传文件,可以在 get_upload_url() 的 file_name 前拼上任意层级的目录前缀,例如:

upload_url = page.get_upload_url(f"/{username}/pictures/{f.name}", 600)

官方文档特别说明:/{username}/pictures 这些目录如果不存在,会在 upload_dir 内被自动创建。

启用内置上传存储

要让 Flet 把上传的文件实际保存到磁盘,需要在 ft.run() 中通过 upload_dir 参数指定目录(绝对或相对路径均可):

ft.run(main, upload_dir="uploads")

upload_dir 在 app.py 中被接收并解析:相对路径会基于当前工作目录解析为绝对路径(见 app.py 中的 __get_upload_dir_path 辅助函数),随后在服务器启动时作为上传存储的根目录使用。

更进阶的用法是把上传目录放进 assets 目录,这样用户上传的图片、文档或其他媒体文件可以被 Flet 客户端立即访问:

ft.run(main, assets_dir="assets", upload_dir="assets/uploads")

然后在应用中直接展示上传的图片:

ft.Image(src="/uploads/<some-uploaded-picture.png>")

使用任意对象存储

get_upload_url() 生成的是 Flet 内置上传存储的预签名 URL,但上传机制本身并不绑定特定存储。官方文档指出,你可以用 boto3 为 AWS S3 生成预签名上传 URL,同样的技术也适用于 Wasabi、Backblaze、MinIO 以及其他兼容 S3 API 的存储服务。此时 FilePickerUploadFile.upload_url 直接填入这些服务返回的预签名 URL 即可,pick_files() 与 upload() 的调用方式完全不变。

读取文本内容并在 Web 端保存/下载

在 Web 应用中,FilePickerFile.path 始终为 None,无法通过本地路径读取文件内容。此时应在 pick_files() 中传入 with_data=True,让文件内容直接进入 FilePickerFile.bytes。

官方示例 pick_and_save_text_content/main.py 完整演示了这一流程——选择 .txt/.md 文件、读取其文本内容展示,再通过 save_file() 配合 src_bytes 保存或下载:

async def pick_text_file(_: ft.Event[ft.Button]):
    files = await ft.FilePicker().pick_files(
        allow_multiple=False,
        with_data=True,
        file_type=ft.FilePickerFileType.CUSTOM,
        allowed_extensions=["txt", "md"],
    )
    if not files:
        selected_file_name.value = "Selection cancelled"
        return

    selected = files[0]
    selected_file_name.value = f"Selected: {selected.name} ({selected.size} bytes)"
    selected_file_content.value = (
        selected.bytes.decode("utf-8", errors="replace") if selected.bytes else ""
    )

async def save_text_file(_: ft.Event[ft.Button]):
    file_name = "flet_text_content.txt"
    file_path = await ft.FilePicker().save_file(
        file_name=file_name,
        file_type=ft.FilePickerFileType.CUSTOM,
        allowed_extensions=["txt"],
        src_bytes=selected_file_content.value.encode("utf-8"),
    )
    if page.web:
        save_status.value = f"Downloaded as {file_name}"
    else:
        save_status.value = (
            f"Saved to: {file_path}" if file_path else "Save cancelled"
        )

这个示例同时展示了 FilePickerFileType.CUSTOM 与 allowed_extensions 的组合用法(选择与保存时都只允许文本类扩展名),以及 save_file() 在 Web 与原生平台上结果呈现方式的差异(Web 端触发下载,原生端写入磁盘并返回路径)。

总结

FilePicker 是 Flet 文件能力的统一入口:pick_files()、save_file() 与 get_directory_path() 覆盖了文件选择、保存和目录选择三大场景,PickFiles 客户端动作解决了 Web/iOS 上的浏览器手势限制,而 upload() + get_upload_url() + upload_dir 组合则提供了一套从选择到上传再到落盘存储的完整链路。各方法的平台差异(Web 模式下 path 不可用、save_file 需 src_bytes、get_directory_path 不支持)在源码中均有显式校验与文档说明,开发者按本文的对照即可在桌面、移动与 Web 三端写出统一的文件处理代码。所有示例均可在仓库 sdk/python/examples/services/file_picker 目录下找到并直接运行。

登录后查看全文
flet