Marimo 开发

创建具有交互性的 Python 笔记本，使用 marimo 的交互式编程环境。

核心工作流程

从基础开始：阅读 references/core-concepts.md - 包含 marimo 的单元结构、反应性模型、UI 元素和基本示例
使用常见任务的配方：检查 references/recipes.md 以获取代码片段
参考 API 文档：浏览 references/api/ 以获取特定函数的详细信息
故障排除问题：查看 references/faq.md 和 references/troubleshooting.md

关键 Marimo 概念

单元结构

每个 marimo 单元都遵循此结构：

@app.cell
def _():
    # 你的代码在这里
    return

当编辑单元时，只修改函数内的代码 - marimo 自动处理参数和返回。

反应性规则

自动执行：当变量变化时，使用它的单元自动重新运行
不重新声明：变量不能在单元间重新声明
DAG 结构：单元形成有向无环图（无循环依赖）
最后表达式显示：单元中最后一个表达式自动显示
UI 反应性：通过 .value 访问的 UI 元素值触发自动更新
局部变量：以 _ 为前缀的变量（例如 _temp）是单元局部的

导入模式

总是在第一个单元导入 marimo：

@app.cell
def _():
    import marimo as mo
    # 其他导入
    return

常见任务

创建交互式 UI

# 在一个单元中创建 UI 元素
@app.cell
def _():
    slider = mo.ui.slider(0, 100, value=50, label="值")
    slider
    return

# 在另一个单元中使用它的值
@app.cell
def _():
    result = slider.value * 2
    mo.md(f"双倍值：{result}")
    return

处理数据

# 加载并显示数据
@app.cell
def _():
    import polars as pl
    df = pl.read_csv("data.csv")
    df  # 自动显示为表格
    return

# 交互式数据探索
@app.cell
def _():
    mo.ui.data_explorer(df)
    return

SQL 与 DuckDB

@app.cell
def _():
    # marimo 内置 DuckDB 支持
    result = mo.sql(f"""
        SELECT * FROM df WHERE column > 100
    """)
    return

布局

@app.cell
def _():
    # 水平堆栈
    mo.hstack([element1, element2, element3])

    # 垂直堆栈
    mo.vstack([top, middle, bottom])

    # 标签页
    mo.tabs({"标签页 1": content1, "标签页 2": content2})
    return

可视化最佳实践

matplotlib：使用 plt.gca() 作为最后一个表达式（而不是 plt.show()）
plotly：直接返回图形对象
altair：返回图表对象；添加工具提示；直接接受 polars 数据框

参考文档

使用 references/NAVIGATION.md 来理解完整的文档结构。关键参考：

基本阅读

core-concepts.md - 从这里开始了解基础和示例
recipes.md - 常见任务的代码片段

详细指南

reactivity.md - 深入反应性执行
interactivity.md - 构建交互式 UI
best_practices.md - marimo 的编码标准

处理数据

working_with_data/sql.md - SQL 和 DuckDB 集成
working_with_data/dataframes.md - pandas, polars 等
working_with_data/plotting.md - 可视化库

部署

apps.md - 部署为交互式 Web 应用
scripts.md - 作为 Python 脚本运行，带有 CLI 参数

API 参考

api/inputs/ - 所有 UI 元素（滑块、下拉菜单、按钮、表格等）
api/layouts/ - 布局组件（标签页、手风琴、侧边栏等）
api/control_flow.md - 单元执行控制
api/state.md - 状态管理
api/caching.md - 性能优化

故障排除

faq.md - 常见问题和解决方案
troubleshooting.md - 错误修复
debugging.md - 调试技巧

常见陷阱

循环依赖：重新组织代码以消除循环
UI 值访问：不能在定义 UI 元素的同一单元中访问 .value
变量重新声明：每个变量只能在所有单元中定义一次
可视化不显示：确保可视化对象是最后一个表达式
Global 关键字：永远不要使用 global - 违反 marimo 的执行模型

创建笔记本后

运行 marimo check --fix 以自动捕获和修复常见的格式问题并检测陷阱。

快速参考：最常用的 UI 元素

mo.ui.slider(start, stop, value=None, label=None)
mo.ui.dropdown(options, value=None, label=None)
mo.ui.text(value='', label=None)
mo.ui.button(value=None, kind='primary')
mo.ui.checkbox(label='', value=False)
mo.ui.table(data, sortable=True, filterable=True)
mo.ui.data_explorer(df)  # 交互式数据框浏览器
mo.ui.dataframe(df)  # 可编辑的数据框
mo.ui.form(element, label='')  # 在表单中包装元素
mo.ui.array(elements)  # UI 元素数组

查看 references/api/inputs/index.md 以获取完整列表。

快速参考：布局函数

mo.md(text)  # 显示 markdown
mo.hstack(elements)  # 水平布局
mo.vstack(elements)  # 垂直布局
mo.tabs(dict)  # 标签页界面
mo.stop(predicate, output=None)  # 条件执行
mo.output.append(value)  # 追加到输出
mo.output.replace(value)  # 替换输出

查看 references/api/layouts/index.md 以获取所有布局选项。