Flet FilePickerUploadEvent 实战指南:用 on_upload 实现文件上传进度监控
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 的完整使用流程包含三个环节:
- 选文件:调用
FilePicker.pick_files()(或使用PickFiles客户端动作); - 构造上传描述:为每个选中文件创建一个
FilePickerUploadFile,指定upload_url与方法; - 发起上传:调用
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 端实现与事件字段语义,实际开发中建议:
- 先判 error 再读 progress:
error非空即视为本次上传失败,此时progress无意义; - 关注 1.0 与 0.0 两端的确定性:无论文件多小,
0.0与1.0必然各触发一次,可用e.progress == 1.0作为"该文件上传完成"的收尾信号(例如禁用该文件对应的进度行、显示完成标记); - 大文件才有多段进度:小于 1 MB 的文件只会收到
0.0和1.0两个事件,进度条动画应能容忍"从 0 直接跳到 1"; - 上传前先 pick:
upload()依赖 FilePicker 内部的选择状态,官方文档明确要求先调用pick_files()确保选择非空,否则文件定位会失败; - 服务端 2xx 判定:客户端只把
200~204视为成功,其他状态码会以"Upload endpoint returned code ..."形式进入error字段,排查时可据此区分网络层错误与业务层错误。
通过 FilePickerUploadEvent,Flet 把原本需要自行封装的上传进度上报逻辑收敛为"一个事件对象 + 一个回调",配合 ProgressRing/ProgressBar 的 value 绑定,即可在几行代码内实现完整的文件上传进度界面。