【免费下载链接】flet
Build realtime web, mobile and desktop apps in Python only. No frontend experience required.
导读
本文围绕 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_title | None | 对话框标题 |
initial_directory | None | 对话框初始打开目录 |
file_type | FilePickerFileType.ANY | 可选文件类型,见下文枚举 |
allowed_extensions | None | 仅当 file_type=CUSTOM 时生效,如 ["txt", "md"] |
allow_multiple | False | 是否允许一次选择多个文件 |
with_data | False | 是否将文件内容读入 FilePickerFile.bytes |
compression_quality | 0 | 图片压缩质量(0–100),0 表示不压缩,越界会抛 ValueError |
cancel_upload_on_window_blur | True | 仅 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 内置了跨平台的上传能力,工作流程分两步:
- 先调用
file_picker.pick_files()让用户选择文件——此时不会自动上传,只是把文件引用保存在 FilePicker 内部状态中; - 再调用
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.
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



