marimo UI 组件实战：运行内置 UI 示例并理解 --sandbox 依赖隔离机制-二趣网

marimo UI 组件实战：运行内置 UI 示例并理解 --sandbox 依赖隔离机制

【免费下载链接】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

本文以 examples/ui/README.md 为主线，介绍 marimo（一个响应式 Python Notebook）自带的 UI 组件示例集如何运行、依赖如何随 Notebook 内联声明，以及marimo edit --sandbox标志背后的沙箱实现。读完后你可以直接运行examples/ui/下的全部 38 个交互式示例，并理解 marimo 如何用uv为单个 Notebook 自动构建隔离虚拟环境。

这些示例在演示什么

examples/ui/ 目录存放 marimo 内置 UI 元素的基础示例。每个文件都是一个独立的 marimo Notebook，展示一个marimo.ui组件（按钮、滑块、表单、表格、数据编辑器等）如何在"交互即触发重算"的响应式模型下工作。目录覆盖了从基础控件到复合控件的完整谱系：

基础输入：button.py、checkbox.py、text.py、text_area.py、number.py、slider.py、range_slider.py、switch.py、radio.py、dropdown.py、multiselect.py；
时间与文件：date.py、date_range.py、datetime_input.py、file.py、file_browser.py、download.py；
数据展示与编辑：dataframe.py、table.py、table_advanced.py、data_editor.py、data_explorer.py、matrix.py；
复合与高级控件：form.py、batch.py、batch_and_form.py、layout.py、tabs.py、tabs_advanced.py、code_editor.py、run_button.py、refresh.py、microphone.py、image_comparison_demo.py、arrays_and_dicts.py、array_element.py、dictionary.py、chat.py。

README 同时提醒：刚接触 marimo 的读者可以先在命令行运行marimo tutorial intro和marimo tutorial ui两个内置教程——后者对应仓库中的教程 Notebook marimo/_tutorials/ui.py，它从mo.ui.slider开始演示"与 UI 元素交互会自动运行引用它的单元格"这一核心机制；对聊天机器人（chatbot）方向的示例，仓库另设有专门的 examples/ai/chat 目录，不在本篇 UI 组件的范围内。

响应式交互的基本范式

每个示例都遵循同一套模式：@app.cell中创建 UI 元素并输出（输出即渲染到页面），再让后续单元格引用该元素的.value属性——一旦被引用，UI 值变化就会触发依赖它的单元格自动重新执行。

以 examples/ui/button.py 为例：

@app.cell def _(mo): button = mo.ui.button( value=0, on_click=lambda value: value + 1, label="increment", kind="warn" ) button return (button,) @app.cell def _(button): button.value return

点击按钮触发on_click回调，值从 0 自增，第二个单元格因引用button.value而重新执行。类似的写法出现在 slider.py（mo.ui.slider(start=1, stop=10)）和 refresh.py（mo.ui.refresh(default_interval=1)，定时触发重算）中。

组合场景则体现在 form.py：用mo.md模板占位符加.batch()将多个元素打包，再调用.form()生成带边框/清除按钮的表单，form.value返回包含name、date两个字段的字典：

form = ( mo.md( """ **Your form.** {name} {date} """ ) .batch( name=mo.ui.text(label="name"), date=mo.ui.date(label="date"), ) .form(show_clear_button=True, bordered=False) )

运行示例：依赖是内联在 Notebook 里的

README 的核心操作说明是：每个 Notebook 的依赖以顶层注释（PEP 723 内联脚本元数据）的形式序列化在文件头部。例如 examples/ui/dataframe.py 开头：

# /// script # requires-python = ">=3.12" # dependencies = [ # "marimo", # "vega-datasets==0.9.0", # ] # ///

这段元数据由 marimo/_utils/inline_script_metadata.py 中的PyProjectReader解析（sandbox.py直接 import 它来判断 Notebook 是否携带内联依赖），这也是后文沙箱机制能自动识别依赖的前提。

运行步骤（与 README 一致）：

安装uv；
用沙箱模式打开示例：

uvx marimo edit --sandbox <notebook-url>

例如uvx marimo edit --sandbox examples/ui/dataframe.py。--sandbox标志会在隔离的虚拟环境中打开 Notebook 并自动安装文件头声明的依赖，无需手动pip install。

如果你不想用uv，也可以先手动安装 marimo（pip install marimo等标准方式），然后运行marimo edit <notebook-url>——但此时 Notebook 声明的第三方依赖需要你自己安装。

源码剖析：--sandbox 是如何工作的

README 中--sandbox的行为在 CLI 源码中有完整实现，核心文件是 marimo/_cli/sandbox.py，入口解析在 marimo/_cli/cli.py（--sandbox/--no-sandbox标志定义为可选值）。

resolve_sandbox_mode()将沙箱模式解析为三种状态，对应 marimo/_cli/sandbox.py 中的SandboxMode枚举：

SINGLE（单文件沙箱）：用uv run包裹整个进程。cli.py中的调用链是resolve_sandbox_mode()→run_in_sandbox(sys.argv[1:], name=name, additional_features=["lsp"])，即由 uv 依据文件头的 PEP 723 元数据临时创建 venv 并执行 marimo；
MULTI（多文件沙箱）：当--sandbox作用于一个目录时启用，为每个 Notebook 建立独立 venv 的 IPC kernel；此模式要求pyzmq，源码中对缺失会给出marimo[sandbox]安装提示（marimo/_cli/cli.py）；
None（不沙箱）：普通模式，依赖需自行安装。

值得注意的一个细节是交互式推断：即使你省略--sandbox，maybe_prompt_run_in_sandbox()也会检查目标文件是否携带内联依赖（marimo/_cli/sandbox.py）——若检测到文件头依赖声明且本机有 uv，会弹出"是否在该 Notebook 依赖的沙箱 venv 中运行？"的确认提示（Docker 等非交互终端默认不沙箱）。也就是说，README 推荐显式加--sandbox，本质上是跳过这步确认、确定性地在隔离环境中启动。

小结

examples/ui/README.md 看似简短，实则串起了 marimo 三条产品特性的交叉点：marimo.ui的响应式交互模型（值变化驱动单元格重算）、PEP 723 内联依赖声明（Notebook 即自带 requirements 的纯 Python 文件）、以及uv驱动的--sandbox隔离运行（单文件与目录两种模式）。建议的路径是：先用marimo tutorial ui熟悉交互范式，再按 examples/ui/ 逐个打开示例，最后参考 marimo/_cli/sandbox.py 理解沙箱决策逻辑，即可完整复现 README 描述的全部能力。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析