marimo 文件下载组件 mo.download 完整指南从交互式按钮到 Data URL 的底层实现【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimomo.download是 marimo 中用于在单元格内创建文件下载按钮的核心 UI 组件支持将文本、二进制字节、文件对象乃至 DataFrame 一键导出为本地文件。本文以 docs/api/media/download.md 为骨架结合 组件实现、媒体工具模块、前端渲染插件 与 单元测试完整讲解其参数语义、MIME 推断、懒加载机制与虚拟文件原理读完即可在自己的 marimo 笔记本中产出可直接运行的下载功能。一、组件定位与官方示例download组件属于 marimo 的无状态stateless插件位于marimo/_plugins/stateless/download.py对外通过mo.download(...)调用其前端注册名为marimo-download见 download.py。官方 API 文档页直接内嵌了可运行的完整示例 examples/ui/download.py该示例覆盖了文本、CSV、JSON 三类最常见场景并分别演示了立即生成与点击时才生成懒加载两种模式。二、API 签名与参数详解从源码 download.py 可以看到完整的构造签名marimo.download( data, filenameNone, mimetypeNone, disabledFalse, *, labelDownload, )参数类型默认值说明datastr/bytes/io.BytesIO/io.BufferedReader/ 可调用对象必填下载内容。字符串被解释为 URL可调用对象含 async表示懒加载filenamestr/ 零参可调用对象None下载文件名可传入零参函数在点击时求值以反映最新应用状态mimetypestrNone文件 MIME 类型如text/csv、image/png缺省时根据文件名推断disabledboolFalse是否禁用下载按钮labelstr仅关键字参数Download按钮显示文本几个值得注意的参数语义均有源码与测试佐证字符串data被当作 URL 处理在 data.py 中以http开头的字符串会通过VirtualFile.from_external_url原样透传为外部链接浏览器将直接发起对该 URL 的下载空数据自动禁用按钮__init__中disabled disabled or is_data_empty(data)即传入b、或空BytesIO时按钮自动置灰对应测试 test_download_emptyfilename与mimetype二选一推断MIME 类型优先取显式传入值否则调用guess_mime_type根据文件名/路径猜测仍未知则回退为text/plaindownload.py可调用filename会强制走懒加载路径此时渲染期无法从文件名推断扩展名MIME 推断被跳过并回退为text/plain如需特定类型必须显式传mimetype源码注释与 test_download_lazy_filename_mimetype_fallback 均验证了这一点。三、快速上手三种格式的即时下载以官方示例 examples/ui/download.py 为基础先看即时生成eager模式——数据在单元格执行时就被编码并随按钮一起输出import marimo as mo import json import pandas as pd # 1) 文本文件 text_download mo.download( dataHello, world!.encode(utf-8), filenamehello.txt, mimetypetext/plain, labelDownload text, ) # 2) 用 pandas 导出 CSV df pd.DataFrame({name: [Alice, Bob, Charlie], age: [25, 30, 35]}) csv_download mo.download( datadf.to_csv().encode(utf-8), filenamedata.csv, mimetypetext/csv, labelDownload CSV, ) # 3) JSON 数据 data {message: Hello, count: 42} json_download mo.download( datajson.dumps(data).encode(utf-8), filenamedata.json, mimetypeapplication/json, labelDownload JSON, ) mo.hstack([text_download, csv_download, json_download])这里的关键点是mo.download返回的是一个UIElement对象UIElement[None, None]无值语义仅作渲染将其放入单元格末尾或组合进mo.hstack等布局中即可显示按钮。data必须是可以被编码的字节序列——文本、JSON 等内容务必先.encode(utf-8)。四、支持的数据类型与智能转换data参数的类型别名定义在 download.pystr | bytes | io.BytesIO | io.BufferedReader。此外还可传可调用对象含 async用于懒加载。对于文件对象构造时会做一次特殊处理download.py若传入io.BufferedReader例如open(path, rb)的结果自动取其.name作为文件名、seek(0)后立即读出全部字节——因为流只能读取一次必须在渲染期转成字节缓存。更强大的是底层转换工具io_to_data_urlmedia.py它在懒加载路径和mo.download之外还被广泛复用支持的类型包括BytesIO/BufferedReader读取并 Base64 编码bytes直接编码PIL 图片自动序列化为 PNG保留原格式并编码NumPy 数组经PIL.Image.fromarray转为 PNGpathlib.Path读取文件字节后递归转换字符串http(s)URL 原样返回否则尝试按本地文件路径打开读取DataFramepandas 等支持 narwhals 的对象自动写成 CSV 字节流MIME 为text/csv。也就是说懒加载函数里直接返回一个 DataFrame 或 PIL 图片marimo 也会自动完成序列化。五、懒加载点击时才生成数据懒加载是mo.download最实用的特性把data传成零参函数同步或async后数据只在用户点击按钮的那一刻才会在服务端生成适合大文件导出、耗时计算或依赖最新应用状态如当前表格筛选结果的场景。官方示例 download.py 演示了同步与异步两种写法import time import asyncio import json import pandas as pd # 同步懒加载 def get_text_data(): time.sleep(1) return Hello, world!.encode(utf-8) text_download_lazy mo.download( dataget_text_data, filenamehello.txt, mimetypetext/plain, labelDownload text, ) # 异步懒加载await asyncio.sleep 模拟耗时生成 async def get_csv_data(): await asyncio.sleep(1) _df pd.DataFrame({name: [Alice, Bob, Charlie], age: [25, 30, 35]}) return _df # DataFrame 会被自动转成 CSV csv_download_lazy mo.download( dataget_csv_data, filenamedata.csv, mimetypetext/csv, labelDownload CSV, ) async def get_json_data(): await asyncio.sleep(1) _data {message: Hello, count: 42} return json.dumps(_data).encode(utf-8) json_download_lazy mo.download( dataget_json_data, filenamedata.json, mimetypeapplication/json, labelDownload JSON, ) mo.hstack([text_download_lazy, csv_download_lazy, json_download_lazy])底层机制download.py构造时检测callable(data) or callable(filename)将lazy标记置为True此时不预编码数据按钮的data属性为空串点击按钮后前端通过 RPC 调用注册的load函数Function(nameload, ...)_load在服务端执行若data是协程则await否则直接调用拿到结果再交给io_to_data_url编码为data:...;base64,...形式的 Data URL 返回前端前端拿到 URL 后触发浏览器下载。从 DownloadPlugin.tsx 可以看到前端交互细节懒加载点击期间按钮切换为旋转加载图标Loader2RPC 失败时会弹出 Failed to download 的 toast 提示。测试 test_download_lazy_sync、test_download_lazy_async 验证了同步/异步懒加载最终都会得到data:text/plain;base64前缀的 Data URL。六、动态文件名零参函数在点击时求值filename也可以传零参函数marimo 会在每次点击时调用它从而让下载文件名反映最新的应用状态。这一点在测试中得到了细致验证可调用文件名强制走懒加载路径渲染参数中filename为None、lazy为Truetest_download_lazy_filename文件名是每次 load 都重新求值的不是构造时固定先返回first.txt状态改变后再点返回second.txttest_download_lazy_filename_evaluated_at_call当数据本身是即时数据非 callable而仅文件名是 callable 时load只返回新文件名数据继续复用已随按钮输出的 href避免重复编码test_download_lazy_filename_eager_data_reuses_href。mo.download( databreport content, filenamelambda: freport-{mo.app_meta().query_params.get(date, today)}.txt, )七、MIME 类型与文件名的推断规则marimo 对 MIME 的处理遵循明确的优先级理解它可避免下载文件扩展名或类型不正确的问题显式mimetype优先测试 test_download_mimetype 证明传入mimetypetext/csv后 Data URL 前缀即为data:text/csv;base64无mimetype时从文件名/路径推断guess_mime_type内部使用 Python 标准库mimetypes按扩展名猜测。例如仅传filenameout.xlsx即可正确推断出application/vnd.openxmlformats-officedocument.spreadsheetml.sheet而不是ziptest_download_xlsx_infer_mimetype_from_filename都未知则回退text/plain反向地若仅传mimetype扩展名由mime_type_to_ext即mimetypes.guess_extension生成兜底为.txt用于创建虚拟文件的扩展名download.py。有一个使用陷阱需要留意若filename是可调用对象渲染期无法看到扩展名扩展名推断被跳过、MIME 回退为text/plain因此这类场景请务必显式传mimetype。八、底层原理虚拟文件与 Data URL非懒加载路径中数据不会塞进前端 bundle 传输而是被登记为一个虚拟文件mo_data.any_data(data, extext).urldownload.py。any_data位于 data.py处理逻辑为None或空数据 →EMPTY_VIRTUAL_FILEdata:开头的字符串 → 按 Base64 解码为字节http开头的字符串 →VirtualFile.from_external_url原样透传外部 URLbytes/ 字符串 /BytesIO→ 分别构建VirtualFileLifecycleItem并注册进单元格生命周期浏览器端通过 marimo 服务提供的虚拟文件端点按需拉取从而避免大体积 Base64 直接内联到渲染消息中。这条链路解释了为什么即时模式也能高效处理较大文件按钮的href指向虚拟文件而非内联的巨型字符串数据按需从服务端加载。九、导出场景的同类能力mo.download是通用的下载组件而 marimo 中还有两处与下载紧密相关但定位不同的能力可作对照mo.ui.table与mo.ui.dataframe内置show_download参数和download_as后端函数支持将表格数据按 CSV/JSON 等格式直接导出见 table.py 与 dataframe.py笔记本级导出HTML、Markdown、PDF 等走的是 export 端点 与_export包属应用发布范畴与单元格内交互下载按钮是两套机制。若需求是让用户下载当前表格的筛选结果优先考虑mo.ui.table自带的下载按钮若需求是下载任意自定义内容则mo.download是更直接的答案。十、注意事项小结综合源码与测试使用mo.download时记住以下几点即可避免绝大多数问题文本、JSON 等内容必须先.encode(utf-8)转为字节再传给data大文件或耗时生成优先使用懒加载传函数而非数据本身避免单元格执行时阻塞与不必要的编码开销需要自定义扩展名/类型时显式传mimetype尤其在使用可调用filename或非标准扩展名如.xlsx时空数据会自动禁用按钮无需手动判断如需强制禁用可显式传disabledTrue测试 test_download_disabledlabel支持通过渲染后的 HTML 定制按钮文本前端使用renderHTML渲染标签DownloadPlugin.tsxmo.download返回无值的UIElement只能用于展示不能像mo.ui.button那样读取点击值——下载动作完全由前端与loadRPC 驱动。从一行mo.download(data..., filename..., mimetype...)到点击按钮触发浏览器下载背后串联了虚拟文件登记、MIME 推断、RPC 懒加载与前端插件渲染的完整链路。理解这套机制后无论是导出 CSV/JSON、序列化图片还是按最新状态动态命名文件都可以在 marimo 中轻松实现。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
marimo 文件下载组件 mo.download 完整指南：从交互式按钮到 Data URL 的底层实现
marimo 文件下载组件 mo.download 完整指南从交互式按钮到 Data URL 的底层实现【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimomo.download是 marimo 中用于在单元格内创建文件下载按钮的核心 UI 组件支持将文本、二进制字节、文件对象乃至 DataFrame 一键导出为本地文件。本文以 docs/api/media/download.md 为骨架结合 组件实现、媒体工具模块、前端渲染插件 与 单元测试完整讲解其参数语义、MIME 推断、懒加载机制与虚拟文件原理读完即可在自己的 marimo 笔记本中产出可直接运行的下载功能。一、组件定位与官方示例download组件属于 marimo 的无状态stateless插件位于marimo/_plugins/stateless/download.py对外通过mo.download(...)调用其前端注册名为marimo-download见 download.py。官方 API 文档页直接内嵌了可运行的完整示例 examples/ui/download.py该示例覆盖了文本、CSV、JSON 三类最常见场景并分别演示了立即生成与点击时才生成懒加载两种模式。二、API 签名与参数详解从源码 download.py 可以看到完整的构造签名marimo.download( data, filenameNone, mimetypeNone, disabledFalse, *, labelDownload, )参数类型默认值说明datastr/bytes/io.BytesIO/io.BufferedReader/ 可调用对象必填下载内容。字符串被解释为 URL可调用对象含 async表示懒加载filenamestr/ 零参可调用对象None下载文件名可传入零参函数在点击时求值以反映最新应用状态mimetypestrNone文件 MIME 类型如text/csv、image/png缺省时根据文件名推断disabledboolFalse是否禁用下载按钮labelstr仅关键字参数Download按钮显示文本几个值得注意的参数语义均有源码与测试佐证字符串data被当作 URL 处理在 data.py 中以http开头的字符串会通过VirtualFile.from_external_url原样透传为外部链接浏览器将直接发起对该 URL 的下载空数据自动禁用按钮__init__中disabled disabled or is_data_empty(data)即传入b、或空BytesIO时按钮自动置灰对应测试 test_download_emptyfilename与mimetype二选一推断MIME 类型优先取显式传入值否则调用guess_mime_type根据文件名/路径猜测仍未知则回退为text/plaindownload.py可调用filename会强制走懒加载路径此时渲染期无法从文件名推断扩展名MIME 推断被跳过并回退为text/plain如需特定类型必须显式传mimetype源码注释与 test_download_lazy_filename_mimetype_fallback 均验证了这一点。三、快速上手三种格式的即时下载以官方示例 examples/ui/download.py 为基础先看即时生成eager模式——数据在单元格执行时就被编码并随按钮一起输出import marimo as mo import json import pandas as pd # 1) 文本文件 text_download mo.download( dataHello, world!.encode(utf-8), filenamehello.txt, mimetypetext/plain, labelDownload text, ) # 2) 用 pandas 导出 CSV df pd.DataFrame({name: [Alice, Bob, Charlie], age: [25, 30, 35]}) csv_download mo.download( datadf.to_csv().encode(utf-8), filenamedata.csv, mimetypetext/csv, labelDownload CSV, ) # 3) JSON 数据 data {message: Hello, count: 42} json_download mo.download( datajson.dumps(data).encode(utf-8), filenamedata.json, mimetypeapplication/json, labelDownload JSON, ) mo.hstack([text_download, csv_download, json_download])这里的关键点是mo.download返回的是一个UIElement对象UIElement[None, None]无值语义仅作渲染将其放入单元格末尾或组合进mo.hstack等布局中即可显示按钮。data必须是可以被编码的字节序列——文本、JSON 等内容务必先.encode(utf-8)。四、支持的数据类型与智能转换data参数的类型别名定义在 download.pystr | bytes | io.BytesIO | io.BufferedReader。此外还可传可调用对象含 async用于懒加载。对于文件对象构造时会做一次特殊处理download.py若传入io.BufferedReader例如open(path, rb)的结果自动取其.name作为文件名、seek(0)后立即读出全部字节——因为流只能读取一次必须在渲染期转成字节缓存。更强大的是底层转换工具io_to_data_urlmedia.py它在懒加载路径和mo.download之外还被广泛复用支持的类型包括BytesIO/BufferedReader读取并 Base64 编码bytes直接编码PIL 图片自动序列化为 PNG保留原格式并编码NumPy 数组经PIL.Image.fromarray转为 PNGpathlib.Path读取文件字节后递归转换字符串http(s)URL 原样返回否则尝试按本地文件路径打开读取DataFramepandas 等支持 narwhals 的对象自动写成 CSV 字节流MIME 为text/csv。也就是说懒加载函数里直接返回一个 DataFrame 或 PIL 图片marimo 也会自动完成序列化。五、懒加载点击时才生成数据懒加载是mo.download最实用的特性把data传成零参函数同步或async后数据只在用户点击按钮的那一刻才会在服务端生成适合大文件导出、耗时计算或依赖最新应用状态如当前表格筛选结果的场景。官方示例 download.py 演示了同步与异步两种写法import time import asyncio import json import pandas as pd # 同步懒加载 def get_text_data(): time.sleep(1) return Hello, world!.encode(utf-8) text_download_lazy mo.download( dataget_text_data, filenamehello.txt, mimetypetext/plain, labelDownload text, ) # 异步懒加载await asyncio.sleep 模拟耗时生成 async def get_csv_data(): await asyncio.sleep(1) _df pd.DataFrame({name: [Alice, Bob, Charlie], age: [25, 30, 35]}) return _df # DataFrame 会被自动转成 CSV csv_download_lazy mo.download( dataget_csv_data, filenamedata.csv, mimetypetext/csv, labelDownload CSV, ) async def get_json_data(): await asyncio.sleep(1) _data {message: Hello, count: 42} return json.dumps(_data).encode(utf-8) json_download_lazy mo.download( dataget_json_data, filenamedata.json, mimetypeapplication/json, labelDownload JSON, ) mo.hstack([text_download_lazy, csv_download_lazy, json_download_lazy])底层机制download.py构造时检测callable(data) or callable(filename)将lazy标记置为True此时不预编码数据按钮的data属性为空串点击按钮后前端通过 RPC 调用注册的load函数Function(nameload, ...)_load在服务端执行若data是协程则await否则直接调用拿到结果再交给io_to_data_url编码为data:...;base64,...形式的 Data URL 返回前端前端拿到 URL 后触发浏览器下载。从 DownloadPlugin.tsx 可以看到前端交互细节懒加载点击期间按钮切换为旋转加载图标Loader2RPC 失败时会弹出 Failed to download 的 toast 提示。测试 test_download_lazy_sync、test_download_lazy_async 验证了同步/异步懒加载最终都会得到data:text/plain;base64前缀的 Data URL。六、动态文件名零参函数在点击时求值filename也可以传零参函数marimo 会在每次点击时调用它从而让下载文件名反映最新的应用状态。这一点在测试中得到了细致验证可调用文件名强制走懒加载路径渲染参数中filename为None、lazy为Truetest_download_lazy_filename文件名是每次 load 都重新求值的不是构造时固定先返回first.txt状态改变后再点返回second.txttest_download_lazy_filename_evaluated_at_call当数据本身是即时数据非 callable而仅文件名是 callable 时load只返回新文件名数据继续复用已随按钮输出的 href避免重复编码test_download_lazy_filename_eager_data_reuses_href。mo.download( databreport content, filenamelambda: freport-{mo.app_meta().query_params.get(date, today)}.txt, )七、MIME 类型与文件名的推断规则marimo 对 MIME 的处理遵循明确的优先级理解它可避免下载文件扩展名或类型不正确的问题显式mimetype优先测试 test_download_mimetype 证明传入mimetypetext/csv后 Data URL 前缀即为data:text/csv;base64无mimetype时从文件名/路径推断guess_mime_type内部使用 Python 标准库mimetypes按扩展名猜测。例如仅传filenameout.xlsx即可正确推断出application/vnd.openxmlformats-officedocument.spreadsheetml.sheet而不是ziptest_download_xlsx_infer_mimetype_from_filename都未知则回退text/plain反向地若仅传mimetype扩展名由mime_type_to_ext即mimetypes.guess_extension生成兜底为.txt用于创建虚拟文件的扩展名download.py。有一个使用陷阱需要留意若filename是可调用对象渲染期无法看到扩展名扩展名推断被跳过、MIME 回退为text/plain因此这类场景请务必显式传mimetype。八、底层原理虚拟文件与 Data URL非懒加载路径中数据不会塞进前端 bundle 传输而是被登记为一个虚拟文件mo_data.any_data(data, extext).urldownload.py。any_data位于 data.py处理逻辑为None或空数据 →EMPTY_VIRTUAL_FILEdata:开头的字符串 → 按 Base64 解码为字节http开头的字符串 →VirtualFile.from_external_url原样透传外部 URLbytes/ 字符串 /BytesIO→ 分别构建VirtualFileLifecycleItem并注册进单元格生命周期浏览器端通过 marimo 服务提供的虚拟文件端点按需拉取从而避免大体积 Base64 直接内联到渲染消息中。这条链路解释了为什么即时模式也能高效处理较大文件按钮的href指向虚拟文件而非内联的巨型字符串数据按需从服务端加载。九、导出场景的同类能力mo.download是通用的下载组件而 marimo 中还有两处与下载紧密相关但定位不同的能力可作对照mo.ui.table与mo.ui.dataframe内置show_download参数和download_as后端函数支持将表格数据按 CSV/JSON 等格式直接导出见 table.py 与 dataframe.py笔记本级导出HTML、Markdown、PDF 等走的是 export 端点 与_export包属应用发布范畴与单元格内交互下载按钮是两套机制。若需求是让用户下载当前表格的筛选结果优先考虑mo.ui.table自带的下载按钮若需求是下载任意自定义内容则mo.download是更直接的答案。十、注意事项小结综合源码与测试使用mo.download时记住以下几点即可避免绝大多数问题文本、JSON 等内容必须先.encode(utf-8)转为字节再传给data大文件或耗时生成优先使用懒加载传函数而非数据本身避免单元格执行时阻塞与不必要的编码开销需要自定义扩展名/类型时显式传mimetype尤其在使用可调用filename或非标准扩展名如.xlsx时空数据会自动禁用按钮无需手动判断如需强制禁用可显式传disabledTrue测试 test_download_disabledlabel支持通过渲染后的 HTML 定制按钮文本前端使用renderHTML渲染标签DownloadPlugin.tsxmo.download返回无值的UIElement只能用于展示不能像mo.ui.button那样读取点击值——下载动作完全由前端与loadRPC 驱动。从一行mo.download(data..., filename..., mimetype...)到点击按钮触发浏览器下载背后串联了虚拟文件登记、MIME 推断、RPC 懒加载与前端插件渲染的完整链路。理解这套机制后无论是导出 CSV/JSON、序列化图片还是按最新状态动态命名文件都可以在 marimo 中轻松实现。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
