Reflex 文件上传与下载完全指南Assets、Upload 目录与 rx.download / rx.upload 实战【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex本文是 ReflexWeb apps in pure Python 官方文档《Files》的技术深化指南系统讲解 Reflex 应用中文件的两大类处理下载rx.download事件与普通链接两种方式与上传rx.upload组件 后端事件处理器。文中所有概念均以当前仓库 docs/assets/upload_and_download_files.md 为骨架并补充了仓库源码reflex/_upload.py、packages/reflex-components-core/src/reflex_components_core/core/upload.py、packages/reflex-base/src/reflex_base/event/init.py中的实现细节。读完本文你将能在 Reflex 应用中让用户下载服务器文件含改名与动态数据下载、搭建拖拽式文件上传界面并正确区分Assets 静态资源与Upload 上传目录的职责边界。1. 概念前置Assets 与 Upload Directory 的区别任何 Reflex 应用都会同时面对两类文件Assets静态资源随应用打包发布的文件如图片、样式表、脚本位于仓库根目录assets/文件夹或与 Python 源文件并列shared assets。Upload Directory上传目录应用运行期间由用户上传或后端动态生成的临时文件默认存放在uploaded_files/目录可通过环境变量配置。两者的核心差异可归纳为下表特性Assets静态资源Upload Directory上传目录用途随应用打包的静态文件图片、样式表、脚本运行期间用户上传或后端生成的动态文件位置assets/文件夹或 Python 文件旁shared assetsuploaded_files/目录可配置访问方式rx.asset()或直接路径引用rx.get_upload_url()使用场景属于应用代码库的一部分用户通过应用上传或生成可用时机编译期可用运行期可用从源码看上传目录的默认位置由 packages/reflex-base/src/reflex_base/environment.py#L598-L601 中的环境变量REFLEX_UPLOADED_FILES_DIR定义默认值为Path(constants.Dirs.UPLOADED_FILES)即uploaded_files/# 位于 packages/reflex-base/src/reflex_base/environment.py REFLEX_UPLOADED_FILES_DIR: EnvVar[Path] env_var( Path(constants.Dirs.UPLOADED_FILES) )而rx.get_upload_dir()见 packages/reflex-components-core/src/reflex_components_core/core/upload.py#L152-L162在每次调用时会读取该环境变量、创建目录mkdir(parentsTrue, exist_okTrue)并返回Path对象——这意味着你可以在事件处理器里用它拿到上传文件应该写到哪里的真实路径。关于 Assets 的更多细节可参考 docs/assets/overview.md。2. 下载文件DownloadReflex 为让用户把服务器上的文件下载到本地提供了两种方式。2.1 方式一普通链接rx.link最简单的做法直接在rx.link中提供资源的路径点击链接后浏览器会按资源类型决定显示或下载例如图片会被打开压缩包会被下载rx.link(Download, href/reflex_banner.webp)这种方式适合那些浏览器本来就能展示的静态资源。当前仓库的示例应用app/assets/reflex_banner.webp即属于此类可直接引用的资源。2.2 方式二rx.download 事件使用rx.download事件浏览器始终会触发下载行为即使该文件本可以被浏览器直接展示如图片。此外rx.download还能从另一个后端事件处理器中触发灵活性更高。基础用法——点击按钮下载指定 URLrx.button( Download, on_clickrx.download(url/reflex_banner.webp), )指定下载后的文件名rx.download允许你指定一个与服务器端不同的文件名rx.button( Download and Rename, on_clickrx.download(url/reflex_banner.webp, filenamedifferent_name_logo.png), )直接下载后端数据data 参数当要下载的数据没有一个已知 URL时可以从后端把data直接传给rx.downloadimport random class DownloadState(rx.State): rx.event def download_random_data(self): return rx.download( data,.join([str(random.randint(0, 100)) for _ in range(10)]), filenamerandom_numbers.csv, ) def download_random_data_button(): return rx.button( Download random numbers, on_clickDownloadState.download_random_data )data参数支持的类型str或bytes数据data:URIPIL.Image任意 state Var状态变量。如果传入的 Var 本身不是字符串它会被JSON.stringify转换为字符串——这意味着复杂的 state 结构可以直接以 JSON 文件的形式提供给用户下载。2.3 rx.download 的底层实现源码级解析rx.download定义于 packages/reflex-base/src/reflex_base/event/init.py#L1706-L1783签名如下def download( url: str | Var | None None, filename: str | Var | None None, data: str | bytes | Var | None None, mime_type: str | Var | None None, ) - EventSpec:其核心行为可在源码中直接验证URL 校验url若是字符串必须以/开头否则抛出ValueError。文件名推断如果提供了url而未提供filename会自动从 URL 末尾推断文件名url.rpartition(/)[-1]。URL 与 data 互斥同时提供url和data会抛出ValueError。data 的三种编码路径str类型 → 默认mime_typetext/plain以data:{mime_type};base64,...形式编码bytes类型 → 默认mime_typeapplication/octet-stream同样以 base64 data URI 编码Var类型 → 在前端检查其是否已经是data:URIis_data_url是则原样使用否则将 Var 序列化后包装为data:{mime_type},...URI对应文档中提到的JSON.stringify行为。最终通过server_side(_download, ...)生成一个客户端事件规范EventSpec返回。注意data接受str/bytes但如果传入其他类型如直接传int源码会抛出ValueError: Invalid data type ... for download. Use str or bytes.——请确保传给data的内容是字符串或字节流。rx.download的完整参考页见 docs/api-reference/special_events.md 中的rx.download一节。3. 上传文件Upload上传让用户以提交文件的方式与应用交互而不仅仅是通过表单填写数据。Reflex 的上传组件是rx.upload。3.1 基础用法def index(): return rx.fragment( rx.upload(rx.text(Upload files), rx.icon(tagupload)), rx.button(on_submitState.your_upload_handler) )要点rx.upload(...)渲染一个拖拽/点击均可的上传区域其子元素rx.text、rx.icon定义了区域内的提示内容上传的文件由你自定义的后端事件处理器State.your_upload_handler接收处理。3.2 常用属性源码确认在 packages/reflex-components-core/src/reflex_components_core/core/upload.py#L244-L291 中Upload组件基于react-dropzone15.0.0暴露了以下可配置属性属性类型说明acceptdict接受的文件类型键为 MIME 类型、值为格式数组参考 MDN MIME 类型列表disabledbool是否禁用上传区域max_filesint最多上传文件数max_sizeint单文件最大字节数min_sizeint单文件最小字节数multiplebool是否允许多文件上传默认 True在create中通过props.setdefault(multiple, True)设置no_clickbool是否禁用点击上传no_dragbool是否禁用拖拽上传no_keyboardbool是否禁用空格/回车键上传on_dropEventHandler文件拖入时触发的事件on_drop_rejectedEventHandler文件被拒绝不符合条件时触发的事件drag_active_styleStyle拖拽进行中时应用的样式值得注意的源码细节若未提供on_drop组件会默认保存文件供稍后处理upload_props[on_drop] upload_file(upload_id)若未提供on_drop_rejected被拒绝的文件会弹出默认的错误 toast_default_drop_rejected显示每个被拒绝文件及其错误信息组件默认添加rx-Uploadclass 名便于样式定制。3.3 文件在服务端的表示UploadFile上传到服务器的每个文件在事件处理器中是一个UploadFile对象。其定义位于 packages/reflex-components-core/src/reflex_components_core/core/_upload.py#L40-L76基于 Starlette 的StarletteUploadFile扩展class UploadFile(StarletteUploadFile): file: BinaryIO path: Path | None dataclasses.field(defaultNone) size: int | None dataclasses.field(defaultNone) headers: Headers dataclasses.field(default_factoryHeaders)关键点filename/name属性返回上传文件的原始文件名size属性给出文件字节大小源码还实现了文件名净化_sanitize_upload_filename与分块上传UploadChunk、UploadChunkIterator等机制用于支持大文件流式传输。在事件处理器中你可以这样读取文件内容并保存到上传目录class UploadState(rx.State): rx.event async def handle_upload(self, files: list[rx.UploadFile]): upload_dir rx.get_upload_dir() # 返回 uploaded_files/ 的 Path for file in files: data await file.read() (upload_dir / file.filename).write_bytes(data)rx.get_upload_dir()返回配置的上传目录 Path见 packages/reflex-components-core/src/reflex_components_core/core/upload.py#L152-L162目录不存在时会自动创建若想在前端渲染上传后的文件如图片预览用rx.get_upload_url(file_path)获取可访问的 URL见同文件 L176-L187它基于后端UPLOAD端点前缀拼接路径。4. 配置上传目录上传目录的位置可通过环境变量REFLEX_UPLOADED_FILES_DIR修改默认值为uploaded_files/。例如在部署环境中export REFLEX_UPLOADED_FILES_DIR/var/data/myapp_uploads该配置在 packages/reflex-base/src/reflex_base/environment.py#L598-L601 中定义并影响rx.get_upload_dir()与上传保存逻辑。生产部署时建议将上传目录挂载到持久化存储如卷或对象存储以免容器重建后数据丢失。5. 完整示例上传 下载的闭环将本文内容串起来一个上传 CSV、随后可下载的最小闭环应用大致如下import reflex as rx class FileState(rx.State): files: list[rx.UploadFile] [] rx.event async def handle_upload(self, files: list[rx.UploadFile]): 保存用户上传的文件到上传目录。 upload_dir rx.get_upload_dir() for file in files: data await file.read() (upload_dir / file.filename).write_bytes(data) self.files files rx.event def download_original(self): 从后端事件处理器触发下载。 return rx.download(urlf/uploaded_files/{self.files[0].filename}) def index(): return rx.vstack( rx.upload( rx.text(拖拽文件到这里或点击上传), on_dropFileState.handle_upload, multipleTrue, ), rx.button(下载刚上传的文件, on_clickFileState.download_original), ) app rx.App() app.add_page(index)提示直接通过 URL 下载上传目录中的文件时路径前缀与上传目录名一致默认/uploaded_files/...如需更强的访问控制可在后端事件中结合鉴权逻辑自行决定是否返回rx.download。6. 总结场景推荐做法下载静态资源图片/压缩包rx.link(..., href/xxx.webp)强制触发下载、支持改名rx.button(on_clickrx.download(url..., filename...))后端动态生成数据下载rx.download(data..., filename...)data可为str/bytes/data:URI/PIL.Image/Var用户上传文件rx.upload(...) 后端事件处理器接收list[rx.UploadFile]获取上传文件的可访问 URLrx.get_upload_url(file_path)修改上传目录位置环境变量REFLEX_UPLOADED_FILES_DIR通过本指南你已掌握 Reflex 文件体系的完整脉络Assets 管编译期随包发布的静态资源Upload 目录管运行期用户产生的动态文件rx.download负责把服务器数据安全送到用户本地rx.upload负责把用户文件收进服务器。相关组件参考页见 docs/library/forms/upload.mdrx.download参考页见 docs/api-reference/special_events.md。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考