Flet FilePicker 文件选择与上传完整指南:原生对话框、内置上传存储与进度监控

  • 前端
  • 跨平台
  • 桌面应用
  • 移动开发

【免费下载链接】flet

Build realtime web, mobile and desktop apps in Python only. No frontend experience required.

项目地址: https://gitcode.com/gh_mirrors/fl/flet
点击查看 免费下载

导读

本文围绕 Flet 的 FilePicker 服务控件,系统讲解如何在纯 Python 应用中弹出操作系统原生文件对话框(选择文件、保存文件、选择目录),以及如何借助 page.get_upload_url() 与 upload_dir 实现内置的上传存储和上传进度实时监控。读完本文,你将能够用 20 行左右的 Python 代码,在 Web、桌面、iOS、Android 全平台实现"选择文件 → 上传 → 显示进度 → 展示已上传图片"的完整链路。

FilePicker 是什么

FilePicker 是 Flet 提供的一个服务型控件(Service),其底层基于 Flutter 生态中成熟的 file_picker 包实现。在 Flet 中,它通过 Python 端与 Flutter 客户端之间的消息通道工作:Python 端调用方法下发指令(如 pick_files),客户端随即打开操作系统原生对话框,并把结果(文件路径、文件名、文件内容等)回传给 Python 端。

在本文对应的发布日志 2022-09-02-file-picker-and-uploads.md 中,这一功能作为里程碑式能力发布,其核心特性包括:

  • 三种原生对话框:选择文件(单选/多选、按类型过滤)、保存文件、选择目录;
  • 全平台覆盖:Web、macOS、Windows、Linux、iOS、Android 均可使用;
  • 内置上传能力:选择文件后可通过预签名 URL 上传到 Flet 内置上传存储,或任何 S3 兼容的对象存储;
  • 上传进度事件:客户端异步逐个上传,并通过回调持续上报进度。

三种对话框与平台差异

FilePicker 提供三种对话框,对应三个核心方法:

对话框对应方法返回内容Web 端可用性
选择文件pick_files()一个或多个文件的引用(FilePickerFile 列表)✅ 可用(仅用于上传场景)
保存文件save_file()用户选择的文件完整路径❌ 需配合 src_bytes 触发浏览器下载
选择目录get_directory_path()用户选择的目录完整路径❌ 不支持(源码中直接抛异常)

为什么 Web 端受限? 浏览器出于安全考虑不会暴露本地文件的真实路径,因此 Web 模式下 pick_files() 拿不到 FilePickerFile.path,只能拿到文件名与内容引用,天然与"上传"绑定。get_directory_path() 在 Web 模式下则会抛出 FletUnsupportedPlatformException,源码见 file_picker.py:

if self.page.web:
    raise FletUnsupportedPlatformException(
        "get_directory_path is not supported in web mode"
    )

桌面端是 FilePicker 发挥最大价值的地方:三种对话框都能返回所选文件与目录的完整路径,可以直接用于桌面应用的本地文件管理、导入导出等场景。

另外从源码可知,Linux 桌面端运行 FilePicker 需要安装 Zenity(浏览器模式不需要):

sudo apt-get install zenity

在应用中使用 FilePicker

挂载到 Page

FilePicker 尺寸为 0×0,即使如此,如果把它放进 Row 或 Column,仍会被当作普通控件参与布局。因此推荐把它挂到页面的服务(overlay)集合中,不影响应用布局。发布日志当时的写法是:

import flet as ft

file_picker = ft.FilePicker()
page.overlay.append(file_picker)
page.update()

在本文对应的仓库版本中,服务控件统一挂载到 page.services,写法如下:

import flet as ft

file_picker = ft.FilePicker(on_result=on_dialog_result, on_upload=on_upload_progress)
page.services.append(file_picker)

仓库中的官方示例 pick_files_action/main.py 即采用 page.services.append(file_picker) 的写法。

打开对话框

调用三个方法之一即可打开对应的原生对话框,配合 lambda 非常简洁:

ft.ElevatedButton(
    "Choose files...",
    on_click=lambda _: file_picker.pick_files(allow_multiple=True),
)

各方法的完整参数(均可在 file_picker.py 源码中核对):

pick_files()

参数默认值说明
dialog_titleNone对话框标题
initial_directoryNone对话框初始打开目录
file_typeFilePickerFileType.ANY可选文件类型,见下文枚举
allowed_extensionsNone仅当 file_type=CUSTOM 时生效,如 ["txt", "md"]
allow_multipleFalse是否允许一次选择多个文件
with_dataFalse是否将文件内容读入 FilePickerFile.bytes
compression_quality0图片压缩质量(0–100),0 表示不压缩,越界会抛 ValueError
cancel_upload_on_window_blurTrue仅 Web:浏览器窗口失焦时是否视为取消选择,慢网络下可设为 False

save_file() 额外支持 file_name(默认文件名)与 src_bytes(文件内容字节)。注意:在 Web、iOS、Android 模式必须提供 src_bytes,否则源码会直接抛出 ValueError;Web 模式还必须提供 file_name。

get_directory_path() 仅支持 dialog_title 与 initial_directory,且 Web 模式不可用。

FilePickerFileType 是源码中定义的枚举,取值包括:ANY(任意类型)、MEDIA(视频+图片)、IMAGE、VIDEO、AUDIO、CUSTOM(自定义扩展名)。

处理对话框结果

发布日志中,对话框关闭后通过 FilePicker.on_result 事件回调接收结果,事件对象包含两类属性:

  • files —— 仅"选择文件"对话框产生,为选中文件列表;取消则为 None;
  • path —— "保存文件"与"选择目录"对话框产生,为完整路径;取消则为 None。
import flet as ft

def on_dialog_result(e: ft.FilePickerResultEvent):
    print("Selected files:", e.files)
    print("Selected file or directory:", e.path)

file_picker = ft.FilePicker(on_result=on_dialog_result)

最后一次对话框的结果始终保存在 FilePicker.result 属性中,随时可读取。

在当前仓库版本中,pick_files()、save_file()、get_directory_path() 均为异步方法并直接返回结果(pick_files 返回 FilePickerFile 列表,另外两者返回路径字符串,取消时返回 None),而 on_result 事件则主要服务于客户端动作 PickFiles(见下文 Web 注意事项)。FilePickerFile 数据类的字段为:id(本次选择范围内的文件标识)、name(文件名,不含路径)、size(字节数)、path(绝对路径,Web 恒为 None)、bytes(仅 with_data=True 时返回文件内容)。

上传文件

FilePicker 内置了跨平台的上传能力,工作流程分两步:

  1. 先调用 file_picker.pick_files() 让用户选择文件——此时不会自动上传,只是把文件引用保存在 FilePicker 内部状态中;
  2. 再调用 file_picker.upload(),传入待上传文件列表(含目标 URL 与 HTTP 方法 PUT/POST)真正执行上传。

发布日志中的经典示例:

import flet as ft

def upload_files(e):
    upload_list = []
    if file_picker.result != None and file_picker.result.files != None:
        for f in file_picker.result.files:
            upload_list.append(
                ft.FilePickerUploadFile(
                    f.name,
                    upload_url=page.get_upload_url(f.name, 600),
                )
            )
        file_picker.upload(upload_list)

ft.ElevatedButton("Upload", on_click=upload_files)

FilePickerUploadFile 是每个待上传文件的描述符,字段包括:upload_url(上传目标地址,可以是绝对 URL 或 page.get_upload_url() 返回的相对 URL)、method(默认 "PUT",通常为 PUT 或 POST)、id(优先按选择返回的文件 id 匹配)、name(id 缺失或未命中时的回退匹配键)。在客户端 file_picker.dart 中可以看到,上传时先按 id 索引匹配已选文件,未命中再按 name 回退,且每个文件上传成功后会被从内部列表中移除。

生成上传 URL:page.get_upload_url()

page.get_upload_url(file_name, expires) 用于生成指向 Flet 内置上传存储的预签名(presigned)上传 URL,其中:

  • file_name:相对于上传存储的路径;
  • expires:URL 有效期,单位为秒。

其实现位于 page.py,内部委托给 session.connection.get_upload_url(file_name, expires)。

按用户隔离上传目录:如果需要区分不同用户的上传,可在 file_name 前拼接任意层级目录,Flet 会在 upload_dir 内自动创建缺失的目录:

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

开启内置上传存储:upload_dir

要让 Flet 真正把上传文件落盘,需要在 ft.run()(即 flet.app())中通过 upload_dir 参数指定保存目录,支持绝对路径或相对路径:

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

从 app.py 的 __get_upload_dir_path() 源码可见,相对路径会以当前脚本目录(或 --web 模式下的当前工作目录)为基准解析为绝对路径。

把上传目录放进 assets:可以把 upload_dir 指向 assets_dir 内部,这样上传的文件(图片、文档、媒体)可以被 Flet 客户端立即访问:

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

应用内直接展示用户上传的图片:

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

替换为任意存储

get_upload_url() 只是生成预签名 URL 的便捷方式,并非唯一选择。你完全可以使用 boto3 为 AWS S3 生成预签名上传 URL,替换掉 upload_url:

import boto3

s3 = boto3.client("s3")
upload_url = s3.generate_presigned_url(
    "put_object",
    Params={"Bucket": "my-bucket", "Key": f.name},
    ExpiresIn=600,
)

同样的技术适用于 Wasabi、Backblaze、MinIO 等任何 S3 兼容对象存储,只需替换 endpoint。FilePicker.upload() 对上传目标完全无感知,只要 upload_url 可访问即可。

上传进度监控

一旦调用 FilePicker.upload(),Flet 客户端会异步地逐个上传选中的文件,并通过 FilePicker.on_upload 回调持续上报进度:

def on_upload_progress(e: ft.FilePickerUploadEvent):
    print(f"{e.file_name}: {e.progress}")

file_picker = ft.FilePicker(on_upload=on_upload_progress)

FilePickerUploadEvent 的字段为:

  • file_name —— 正在上传的文件名;
  • progress —— 进度值,范围 0.0 到 1.0;
  • error —— 上传失败时的错误信息。

回调频率规则(源码 docstring 与客户端实现双重印证):

  • 每个文件至少回调两次:上传开始前报告 0,上传完成时报告 1.0;
  • 对于 大于 1 MB 的文件,每上传 10% 额外报告一次(即 0.1、0.2……)。

客户端实现细节见 file_picker.dart:上传使用 http.StreamedRequest 以流式方式发送(并设置 contentLength),通过监听读取流累计 bytesSent 计算进度,lastSent += 0.1 控制每 10% 上报一次;当响应状态码不在 200–204 区间时,通过 error 字段上报错误。

仓库中的完整多文件上传进度示例 pick_and_upload/main.py 展示了将进度渲染为 ProgressRing 的写法:

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

选中文件后为每个文件创建一个初始值为 0 的进度环,上传时按 e.file_name 更新对应进度环的 value,界面即实时反映上传进度。

Web 端注意事项:客户端动作 PickFiles

在 Web 应用中(尤其是 iOS 的 Safari),浏览器只允许在用户点击(或按键)手势的原始上下文中打开文件选择框。如果从 on_click 回调里发起 pick_files(),指令先传到 Python 再传回浏览器时,手势权限已经失效——Safari 会静默拒绝,Chrome/Firefox 通常放行,这导致同一个应用在 iPhone/iPad 上无法选文件。

解决方法是把 PickFiles 作为客户端动作直接挂到控件上(action 属性),让对话框在原始手势内打开,选择结果通过 FilePicker.on_result 回到 Python。仓库示例 pick_files_action/main.py:

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

ft.Button(
    content="Select files...",
    icon=ft.Icons.FOLDER_OPEN,
    action=ft.PickFiles(file_picker, allow_multiple=True),
)

PickFiles 类(定义于 file_picker.py)支持与 pick_files() 相同的参数集合,选中文件仍与 file_picker 关联,后续调用 upload() 的方式完全一致。

完整实战示例

综合以上内容,一个覆盖"选文件 → 上传 → 显示进度"的完整应用如下(脱胎于仓库 pick_and_upload/main.py):

import flet as ft

prog_bars: dict[str, ft.ProgressRing] = {}

def main(page: ft.Page):
    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]):
        file_picker = ft.FilePicker(on_upload=on_upload_progress)
        files = await file_picker.pick_files(allow_multiple=True)
        print("Picked files:", files)

        upload_button.disabled = len(files) == 0
        prog_bars.clear()
        upload_progress.controls.clear()
        for f in files:
            prog = ft.ProgressRing(value=0, bgcolor="#eeeeee", width=20, height=20)
            prog_bars[f.name] = prog
            upload_progress.controls.append(ft.Row([prog, ft.Text(f.name)]))

        page.session.set("picker", file_picker)

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

    page.add(
        ft.SafeArea(
            content=ft.Column(
                controls=[
                    ft.Button(content="Select files...", on_click=handle_files_pick),
                    upload_progress := ft.Column(),
                    upload_button := ft.Button(
                        content="Upload", on_click=handle_file_upload, disabled=True
                    ),
                ],
            ),
        )
    )

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

同时,官方文档 FilePicker 服务文档 与仓库示例集(pick_save_and_get_directory_path、pick_and_save_text_content 等)提供了"选择/保存/取目录"、"读取文件文本内容并保存"等更多场景的完整可运行代码。

小结

FilePicker 让纯 Python 的 Flet 应用获得了完整的原生文件交互能力:pick_files() / save_file() / get_directory_path() 覆盖选择、保存、目录三大场景;pick_files() + upload() + get_upload_url() 打通了从选择到上传再到展示的闭环;on_upload 事件则让上传进度可视化成为可能。无论是桌面端追求文件路径的本地文件操作,还是 Web 端配合 PickFiles 客户端动作与内置 upload_dir 存储的多用户上传,这套机制都足够通用且开箱即用。

  • 前端
  • 跨平台
  • 桌面应用
  • 移动开发

【免费下载链接】flet

Build realtime web, mobile and desktop apps in Python only. No frontend experience required.

项目地址: https://gitcode.com/gh_mirrors/fl/flet
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值