Flet FilePicker 完整指南:文件选择、保存与上传的跨平台实战
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_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
需要理解的两点关键差异:
- 结果流向不同:
pick_files()直接返回文件列表;而PickFiles动作的结果通过on_result事件到达——源码中FilePickerResultEvent的 docstring 明确注明它"由PickFiles动作触发,不由pick_files()触发"(见 file_picker.py)。 - 文件仍与 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 上传):
上传存储: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 目录下找到并直接运行。

