Flet FilePickerFile 详解：文件选择结果的数据结构、字段语义与跨平台实战

前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载FilePickerFile是 FletPython 版文件选择服务中描述单个已选文件的数据类pick_files()返回它的列表PickFiles客户端动作通过on_result事件把它的列表交给你的代码FilePicker.upload()又以它为上下文执行文件上传。本文以 filepickerfile.md 页面所渲染的 API 文档为主体结合 file_picker.py 源码与 examples/services/file_picker 下的官方示例逐字段讲解其语义、平台差异并给出从选取到上传、从读取内容到保存下载的完整可运行示例。一、FilePickerFile 是什么在 Flet 中FilePicker是调用系统原生文件选择对话框的服务型控件。当用户选定文件后Flet 并不会直接暴露底层文件句柄而是把每个文件封装成一个FilePickerFile对象携带文件标识、名称、大小、路径和可选内容等元数据。从源码看FilePickerFile是一个标准的dataclass定义于 file_picker.pydataclass class FilePickerFile: id: int name: str size: int path: Optional[str] None bytes: Optional[bytes] None它出现在两条主路径上方法路径调用FilePicker.pick_files()时返回值类型就是list[FilePickerFile]见 file_picker.py。事件路径把PickFiles客户端动作挂到按钮上时用户选择结果通过FilePicker.on_result事件携带事件对象FilePickerResultEvent.files同样是list[FilePickerFile]见 file_picker.py。import flet as ft # 方法路径直接获得文件列表 files: list[ft.FilePickerFile] await ft.FilePicker().pick_files( allow_multipleTrue )二、字段语义详解下表汇总了FilePickerFile的全部字段、类型、是否必填及核心含义可作为查表速记字段类型必填含义idint是选择作用域内的文件标识符由 Flet 分配用于上传匹配namestr是文件基名basename不含目录路径sizeint是文件大小单位字节pathOptional[str]否文件绝对路径仅在可获得时提供bytesOptional[bytes]否文件内容仅当with_dataTrue时返回id选择作用域内的稳定标识id是 Flet 为当前一次选择分配的文件标识只对本次 picker 选择有效。它是上传阶段的首选匹配键FilePickerUploadFile在构造上传描述时优先按id解析被选文件id缺失或找不到时才回退到name见 file_picker.py。ft.FilePickerUploadFile( idfile.id, # 首选匹配键 namefile.name, # 回退匹配键 upload_urlpage.get_upload_url(fdir/{file.name}, 60), )name不含路径的文件名name是文件基名不含任何目录成分。它在界面上最常用于展示例如官方示例中直接把f.name与f.size拼进文本ft.Text(f{f.name} ({f.size} bytes))size字节大小size以字节为单位是服务端校验上传大小、界面展示文件大小时的基础数据。path跨平台差异最大的字段path是文件的绝对路径但并非所有平台都提供Web 模式恒为None。浏览器出于安全策略不会把本地磁盘路径暴露给网页应用**原生平台桌面、移动**下如果系统选择器没有暴露文件系统路径path也仍可能为None。因此在 Web 应用里要读取文件内容不能依赖path而应使用下面的bytes字段。这一点官方 filepicker.md 页面特别强调在 Web 应用中FilePickerFile.path不可用请用pick_files()的with_dataTrue直接取内容。bytes按需读取的文件内容bytes携带文件原始内容只有调用pick_files()或PickFiles动作并设置with_dataTrue时才填充否则为None。从源码看Python 端会对客户端上报的字节数组做一次归一化_normalize_file()把 JSON 反序列化出的list[int]转回bytes见 file_picker.pydef _normalize_file(self, file: dict[str, Any]) - dict[str, Any]: value file.get(bytes) if isinstance(value, list): file[bytes] bytes(value) return file典型用法是读取文本文件内容并解码显示files await ft.FilePicker().pick_files( allow_multipleFalse, with_dataTrue, file_typeft.FilePickerFileType.CUSTOM, allowed_extensions[txt, md], ) if files: text files[0].bytes.decode(utf-8, errorsreplace)完整可运行示例见 pick_and_save_text_content/main.py运行方式为uv run flet run --web main.py三、获取 FilePickerFilepick_files() 方法FilePicker.pick_files()是获取FilePickerFile列表最直接的方式完整签名与参数见 file_picker.pyasync 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/initial_directory对话框标题与初始目录file_type允许的文件类型默认FilePickerFileType.ANYallowed_extensions自定义扩展名白名单仅当file_type为CUSTOM时生效allow_multiple是否允许多选with_data是否把文件内容读入bytescompression_quality图片压缩质量取值01000表示不压缩。传入越界值会抛出ValueError源码第 373-377 行有0 compression_quality 100的校验cancel_upload_on_window_blur仅 Web 生效是否把浏览器窗口失焦视为取消选择在慢网络或慢机器上可设为False避免误丢有效选择。FilePickerFileType枚举取值见 file_picker.py取值含义ANY允许任意文件类型MEDIAVIDEO与IMAGE的组合IMAGE仅图片VIDEO仅视频AUDIO仅音频CUSTOM仅允许allowed_extensions指定的类型最小示例——多选后把文件名拼成一行展示import flet as ft def main(page: ft.Page): selected_files ft.Text() async def handle_pick_files(e: ft.Event[ft.Button]): files await ft.FilePicker().pick_files(allow_multipleTrue) selected_files.value ( , .join(map(lambda f: f.name, files)) if files else Cancelled! ) page.add(ft.SafeArea(contentft.Column(controls[ ft.Button(contentPick files, iconft.Icons.UPLOAD_FILE, on_clickhandle_pick_files), selected_files, ]))) ft.run(main)该示例的完整版同时演示save_file()与get_directory_path()见 pick_save_and_get_directory_path/main.py。四、Web/iOS 场景PickFiles 客户端动作与 on_result浏览器只会在处理点击或按键的原始手势内打开文件选择器。从on_click回调里调用pick_files()往往已经太迟——指令往返一次后浏览器已失去打开选择器的权限Safari 会静默拒绝而 Chrome/Firefox 允许导致同一应用在 iPhone/iPad 上失效官方 filepicker.md 页面有专门警告。解决方案是把PickFiles动作直接挂在控件上让对话框在原始手势内打开file_picker ft.FilePicker(on_resulthandle_result, on_uploadhandle_upload_progress) page.services.append(file_picker) ft.Button( contentSelect files..., iconft.Icons.FOLDER_OPEN, actionft.PickFiles(file_picker, allow_multipleTrue), )此时选择结果不再“返回”给调用方而是到达on_result事件e.files就是list[FilePickerFile]def handle_result(e: ft.FilePickerResultEvent): state.picked_files e.files # 保存 FilePickerFile 列表供上传使用PickFiles与pick_files()参数基本一一对应见 file_picker.py也支持file_type、allowed_extensions、allow_multiple、with_data等并通过__post_init__把参数绑定到 picker 的pick_files调用上。完整可运行示例见 pick_files_action/main.pyexport FLET_SECRET_KEYsome_secret_key uv run flet run --web examples/services/file_picker/pick_files_action/main.py五、从 FilePickerFile 到上传与 FilePickerUploadFile 的配合FilePickerFile的另一半使命是作为上传的“输入上下文”。上传使用独立的FilePickerUploadFile描述符见 file_picker.pydataclass class FilePickerUploadFile: upload_url: str # 上传目标 URL可用 page.get_upload_url() 生成 method: str PUT # 请求方法通常 PUT 或 POST id: Optional[int] None # 首选匹配键 name: Optional[str] None # 回退匹配键官方推荐流程先用pick_files()选取再把返回的FilePickerFile列表转成FilePickerUploadFile列表交给upload()async def handle_file_upload(e: ft.Event[ft.Button]): await file_picker.upload( files[ ft.FilePickerUploadFile( namefile.name, upload_urlpage.get_upload_url(fdir/{file.name}, 60), ) for file in state.picked_files ] )上传进度通过on_upload事件上报每个文件至少回调两次开始时0.0、完成时1.0大于 1 MB 的文件还会在每 10% 增量处再触发见 file_picker.py。示例中用ProgressRing实时展示每个文件的进度def handle_upload_progress(e: ft.FilePickerUploadEvent): prog_bars[e.file_name].value e.progress若要让 Flet 把上传文件落盘在ft.run()中指定upload_dir见 filepicker.mdft.run(main, upload_direxamples)也可以把上传目录放进 assets让上传的图片等文件立即可被客户端访问ft.run(main, assets_dirassets, upload_dirassets/uploads) # 应用内直接展示ft.Image(src/uploads/some-uploaded-picture.png)六、边界与注意事项path不等于可用文件Web 下恒为None原生平台也可能为None。需要文件内容时始终优先使用with_dataTrue的bytes字段。bytes有内存成本只有确需读取内容如 Web 端读取文本、图片预览时才开启with_dataTrue普通上传场景保持关闭可减少不必要的传输。id只在本次选择内有效不要跨会话持久化idname是上传匹配的回退键。Linux 桌面依赖FilePicker控件在 Linux 桌面模式下需要安装 Zenitysudo apt-get install zenity浏览器模式则不需要见 file_picker.py。Web 保存文件的限制在 Web、iOS、Android 上调用save_file()必须提供src_bytesWeb 下还要求file_name否则抛出ValueError见 file_picker.py。七、参考资料与延伸阅读API 文档页filepickerfile.md通过 CrocoDocs 的ClassAll nameflet.FilePickerFile /组件从源码 docstring 渲染生成服务总览页filepicker.md包含用法、Web 选取警告、上传存储与完整示例核心实现file_picker.py含FilePickerFileType、FilePickerFile、FilePickerUploadFile、FilePickerResultEvent、FilePickerUploadEvent、PickFiles的完整定义官方示例目录examples/services/file_picker含pick_files_action、pick_and_upload、pick_and_save_text_content、pick_save_and_get_directory_path四个可运行项目关联类型pickfiles.md客户端动作、filepickerresultevent.md结果事件、filepickeruploadfile.md上传描述符赞分享前端跨平台桌面应用移动开发【免费下载链接】fletBuild realtime web, mobile and desktop apps in Python only. No frontend experience required.项目地址https://gitcode.com/gh_mirrors/fl/flet点击查看免费下载相关推荐Flet FilePickerResultEvent 详解文件选择结果的类型化事件负载Flet FilePickerResultEvent 详解文件选择结果的类型化事件负载 导读 FilePickerResultEvent 是 Flet 文件选前端跨平台桌面应用移动开发Flet 事件详解DismissibleUpdateEvent 拖拽更新事件的结构、字段与实战用法Flet 事件详解DismissibleUpdateEvent 拖拽更新事件的结构、字段与实战用法 DismissibleUpdateEvent 是 Flet前端跨平台桌面应用移动开发Flet ContextMenuSelectEvent 详解右键菜单选中事件的数据结构与实战用法Flet ContextMenuSelectEvent 详解右键菜单选中事件的数据结构与实战用法 ContextMenuSelectEvent 是 Flet前端跨平台桌面应用移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考