Flet FilePickerUploadEvent 实战指南:用 on_upload 实现文件上传进度监控

原创2026-09-23 17:52:581,863 阅读
文章标签:前端跨平台UI组件桌面应用移动开发Web框架

Flet FilePickerUploadEvent 实战指南:用 on_upload 实现文件上传进度监控

FilePickerUploadEvent 是 Flet 中由 FilePicker.upload() 触发上传时携带进度与错误信息的核心事件对象,它通过 FilePicker.on_upload 事件处理器将上传的实时进度(0.0 ~ 1.0)回传给 Python 侧。读完本文,你将掌握 FilePickerUploadEvent 三个字段的语义、上传进度事件的触发时机与频率,并能在真实应用中用它驱动进度条、处理上传失败与多文件上传场景。

一、FilePickerUploadEvent 是什么

FilePickerUploadEvent 定义于 sdk/python/packages/flet/src/flet/controls/services/file_picker.py,是一个基于 Event<a href="https://link.gitcode.com/i/4618e88b3c6ae94446eb6edad5f320f8" target="_blank">"FilePicker"] 的 dataclass,用于承载单次文件上传过程中的状态快照。它是 Flet 文档站中 FilePickerUploadEvent 类型页(即 [website/docs/types/filepickeruploadevent.md)所渲染 API 的权威来源——该类型页通过 <ClassAll name="flet.FilePickerUploadEvent" /> 组件直接内联渲染源码中的 docstring,因此本文以源码实现为准展开讲解。

@dataclass
class FilePickerUploadEvent(Event["FilePicker"]):
    file_name: str
    progress: Optional[float] = None
    error: Optional[str] = None

该事件对象本身不包含文件内容,它只是一个"状态信号":告诉你的 Python 代码哪个文件正在上传、上传到多少了、以及是否出错。

二、三个字段的完整语义

1. file_name: str(必填)

被上传文件的名称(basename)。在多文件上传场景中,file_name 是区分不同上传流的唯一稳定标识,通常直接用作进度组件的键(key):

prog_bars: dict[str, ft.ProgressRing] = {}
def on_upload_progress(e: ft.FilePickerUploadEvent):
    prog_bars[e.file_name].value = e.progress

由于 upload() 是逐文件顺序执行的(见下文 Dart 端实现),同一个 file_name 的事件会在时间上连续出现,可以放心用它作为字典键。

2. progress: Optional[float]

上传进度,取值范围 0.0 到 1.0,None 表示当前无进度信息。其语义在 on_upload 的 docstring 中有明确规定:

  • 每个文件至少触发两次:上传开始前触发一次 0.0,上传完成时触发一次 1.0;
  • 超过 1 MB 的大文件:除首尾外,每增加 10% 增量额外触发一次事件(如 0.1、0.2……0.9)。

这一触发节奏在 Flutter 客户端源码 packages/flet/lib/src/services/file_picker.dart 的 uploadFile() 方法中有精确对应实现:上传开始时先发送 0(// send 0%),随后在流式读取文件块时累计 bytesSent,以 progress = bytesSent / file.size 计算进度,并仅在 progress >= lastSent(即每跨越 0.1 的整数倍)时发送一次,progress != 1.0 的判断保证最终 1.0 由成功回调统一发出。因此前端驱动的 ProgressRing 或 ProgressBar 可以直接把 e.progress 赋值给 value 属性,无需额外换算。

3. error: Optional[str]

上传失败时的错误信息,成功时为 None。从 Dart 端实现看,错误来源有两类:

  • 客户端异常:如无法读取文件流(Cannot read file from null stream)、网络异常,此时 sendProgress(file.name, null, e.toString()) 会把异常字符串传给 error;
  • 服务端响应异常:上传请求返回的状态码不在 200 ~ 204 范围内时,错误信息为 "Upload endpoint returned code {status}: {body}"。

Python 侧判错的写法:

def on_upload_progress(e: ft.FilePickerUploadEvent):
    if e.error:
        print(f"上传失败: {e.file_name} -> {e.error}")
        return
    prog_bars[e.file_name].value = e.progress

注意 error 非空时 progress 通常为 None,两者是互斥状态,处理时建议先判 error。

三、上传流程与事件如何被触发

FilePickerUploadEvent 只能通过 FilePicker.on_upload 事件处理器接收,触发链路如下:

await file_picker.upload(files=[...])  # Python 侧发起
        │
        ▼
客户端按顺序逐文件上传(Flutter: uploadFiles / uploadFile)
        │
        ▼ 每到达 0%、10% 增量、100% 或出错
        ▼
触发 "upload" 事件,构造 FilePickerUploadEvent(file_name, progress, error)
        │
        ▼
Python 侧 on_upload 处理器被调用

关键点:upload() 是异步方法,但上传本身由客户端逐个文件串行执行,Python 侧通过 on_upload 被动接收进度,无需轮询。

FilePickerUploadEvent 的完整使用流程包含三个环节:

  1. 选文件:调用 FilePicker.pick_files()(或使用 PickFiles 客户端动作);
  2. 构造上传描述:为每个选中文件创建一个 FilePickerUploadFile,指定 upload_url 与方法;
  3. 发起上传:调用 FilePicker.upload(files),同时在 FilePicker 构造时挂上 on_upload 处理器。

四、可运行的完整示例:多文件上传 + 实时进度条

仓库自带的 sdk/python/examples/services/file_picker/pick_and_upload/main.py 是官方示例(Web 模式),完整展示了如何用 FilePickerUploadEvent 驱动每个文件的 ProgressRing:

import flet as ft

def main(page: ft.Page):
    prog_bars: dict[str, ft.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

        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)]))

    async def handle_file_upload(e: ft.Event[ft.Button]):
        upload_button.disabled = True
        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
            ]
        )

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

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

要点拆解:

  • 进度条以 file_name 为键:每次 pick 后清空并重建 prog_bars 字典,避免旧文件残留;
  • upload_url 由 page.get_upload_url() 生成:这是 Flet 内部上传存储的预签名 URL,第二个参数 60 是 URL 有效期(秒);
  • ft.run(main, upload_dir="examples"):upload_dir 指定服务端保存上传文件的目录,未设置时上传目标不会落盘;
  • 该示例的元数据(sdk/python/examples/services/file_picker/pick_and_upload/pyproject.toml)声明了 features = ["file upload", "upload progress"]、platforms = ["web"],即该示例定位为 Web 模式的文件上传与进度演示。

另一个官方示例 sdk/python/examples/services/file_picker/pick_files_action/main.py 展示了 PickFiles 客户端动作版本:选文件由按钮的 action=ft.PickFiles(file_picker, allow_multiple=True) 在用户手势内触发(这在 iOS Web 应用中才能弹出文件选择器),结果通过 on_result 到达,之后 upload() 与进度处理方式完全相同。

五、upload() 与 FilePickerUploadFile 的配合细节

FilePicker.upload() 的签名(源码见 file_picker.py):

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

每个 FilePickerUploadFile 包含四个字段:

字段 默认值 说明
upload_url 必填 上传目标 URL,可为绝对 URL 或 page.get_upload_url() 返回的相对 URL
method "PUT" 上传使用的 HTTP 方法,通常为 PUT 或 POST
id None pick_files() 返回的文件标识,同时提供 id 与 name 时优先按 id 匹配
name None 文件名,作为 id 缺失或匹配失败时的回退匹配键

Dart 端 uploadFiles() 的匹配逻辑与此一致:先按 id 在本次选择中定位文件,找不到再按 name 回退;定位成功后逐文件执行上传,成功上传的文件会从客户端选择列表中移除,因此重复上传同一批文件前需重新 pick。若文件匹配失败,客户端仅输出调试日志,不会触发上传事件。

另外两点与上传存储直接相关:

  • 多用户隔离:page.get_upload_url(f"/{username}/pictures/{f.name}", 600) 中带路径前缀的 URL 会在 upload_dir 下自动创建对应目录(详见 website/docs/services/filepicker.md 的说明);
  • 换用任意存储:upload_url 不限于 Flet 内部存储,任何返回 2xx 的预签名上传端点(如 S3 兼容对象存储)均可作为目标,method 按需设为 PUT 或 POST。

六、错误处理与调试建议

综合 Dart 端实现与事件字段语义,实际开发中建议:

  1. 先判 error 再读 progress:error 非空即视为本次上传失败,此时 progress 无意义;
  2. 关注 1.0 与 0.0 两端的确定性:无论文件多小,0.0 与 1.0 必然各触发一次,可用 e.progress == 1.0 作为"该文件上传完成"的收尾信号(例如禁用该文件对应的进度行、显示完成标记);
  3. 大文件才有多段进度:小于 1 MB 的文件只会收到 0.0 和 1.0 两个事件,进度条动画应能容忍"从 0 直接跳到 1";
  4. 上传前先 pick:upload() 依赖 FilePicker 内部的选择状态,官方文档明确要求先调用 pick_files() 确保选择非空,否则文件定位会失败;
  5. 服务端 2xx 判定:客户端只把 200~204 视为成功,其他状态码会以 "Upload endpoint returned code ..." 形式进入 error 字段,排查时可据此区分网络层错误与业务层错误。

通过 FilePickerUploadEvent,Flet 把原本需要自行封装的上传进度上报逻辑收敛为"一个事件对象 + 一个回调",配合 ProgressRing/ProgressBar 的 value 绑定,即可在几行代码内实现完整的文件上传进度界面。

登录后查看全文
flet