marimo 响应式状态详解使用 mo.state 同步 UI 元素与跨单元格状态【免费下载链接】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导读mo.state是 marimo 提供的可变响应式状态mutable reactive stateAPI它返回一对 getter/setter 函数允许你跨单元格维护可变状态并在状态被 setter 更新时自动触发所有读取该状态的单元格重新执行。本文将以 docs/api/state.md 与 docs/guides/state.md 为核心结合 marimo/_runtime/state.py 的源码实现与 tests/_runtime/test_state.py 的测试用例深入讲解mo.state的适用场景、完整用法、状态响应式规则、与 UI 元素的联动方式以及底层运行机制帮助你安全、正确地使用这一高级特性。先决条件你真的需要mo.state吗marimo 官方文档在介绍mo.state之前给出了两条醒目的警告先阅读交互式指南创建交互式元素指南 是学习本文的前置要求。这是一个高级主题超过 99% 的场景下你不需要也不应该使用mo.state因为它可能引入难以排查的 bug。UI 元素本身已经内置了状态——即它们的value属性。例如mo.ui.slider()的 value 是它在区间上的当前位置mo.ui.button()的 value 可以配置为点击计数或True/False切换。更重要的是绑定到全局变量的 UI 元素在被交互时会自动执行所有引用这些变量的单元格你只需读取value属性即可响应变化。这种函数式范式是 marimo 中响应 UI 交互的首选方式例如处理按钮点击根本不需要响应式状态参见 recipes.md 中的 working with buttons 部分。哪些迹象说明你可能需要mo.state根据 docs/guides/state.md只有出现以下需求时才考虑使用mo.state维护历史状态需要维护与某个 UI 元素相关的历史状态且该状态无法从其内置value推导例如用户曾经在表单里输入过的所有值同步两个不同的 UI 元素交互其中一个时另一个也随之联动例如两个元素互相控制跨单元格引入循环需要在运行时引入跨单元格的循环依赖。单向数据流场景下不要使用mo.statedocs/guides/state.md 特别强调如果只是想用一个元素的值去更新另一个元素单向数据流不应该使用mo.state而应使用 marimo 内置的响应式执行机制见 交互式指南。mo.state的价值在于双向绑定和可变状态而非单向派生。mo.state 基本用法getter 与 settermo.state(value, allow_self_loopsFalse)接收一个初始值创建一个状态对象并返回一个二元组getter 函数用于读取状态的当前值setter 函数用于更新状态的值。其函数签名定义于 marimo/_runtime/state.pydef state( value: T, allow_self_loops: bool False ) - tuple[State[T], Callable[[T], None]]:创建状态import marimo as mo get_count, set_count mo.state(0)注意使用mo.state()时必须将 state getter 赋值给全局变量这与 UI 元素的工作方式类似——只有通过全局变量引用的单元格才会被自动重跑。读取状态通过调用 getter 函数访问最新值get_count() # 0更新状态用新值直接覆盖set_count(1) # 现在 get_count() 返回 1基于当前值做增量更新时可以传入一个接收当前值、返回新值的函数set_count(lambda value: value 1)底层实现中SetFunctor.__call__marimo/_runtime/state.py会判断传入的参数是函数还是普通值若是函数types.MethodType或types.FunctionType则以当前值调用它得到新值否则直接赋值。self._state._value ( update(self._state._value) if isinstance(update, (types.MethodType, types.FunctionType)) else update )这意味着任何普通对象包括定义了__call__的实例都会被当作普通值存储而不会被调用——tests/_runtime/test_state.py 中的test_set_to_callable_object用例专门验证了这一点。注意永远不要直接修改状态的内部值只能通过 setter 改变它。源码中的State._value是私有字段绕过 setter 修改会破坏响应式触发机制。状态响应式规则setter 调用后发生了什么核心规则当在一个单元格中调用状态 setter 函数时marimo 会自动运行所有其他引用了该状态 getter 全局变量的单元格。这一规则有两个重要方面只有通过全局变量读取状态 getter 的单元格会被运行调用 setter 的那个单元格不会被重跑即使它引用了 getter——这是为了防止潜在的 bug。若要解除此限制允许调用者单元格被重跑请使用mo.state(value, allow_self_loopsTrue)创建状态。状态与 UI 元素高度相似交互 UI 元素时所有通过全局变量引用该元素的单元格会用新值自动运行同理通过 setter 更新状态时所有通过全局变量引用 getter 的单元格也会自动运行。实现原理StateRegistry 与运行时集成从源码结构看状态的注册与查找由StateRegistrymarimo/_runtime/state.py负责每个State实例在创建时向运行上下文的state_registry注册记录变量名 → State 弱引用的映射register方法register_scope会在单元格执行后扫描新定义的全局变量把其中的State实例纳入注册表retain_active_states按当前活跃变量清理注册表避免变量被删除后状态残留。每次 setter 调用后SetFunctor会调用ctx.register_state_update(self._state)。在 marimo/_runtime/runtime.py 中Kernel.register_state_update记录哪个状态被哪个单元格更新随后由_find_cells_for_statemarimo/_runtime/runtime.py扫描图中所有单元格的 refs找出引用了该状态对象的单元格 ID排除调用 setter 的单元格除非allow_self_loopsTrue将这些单元格标记为 stale 并触发重跑。值得注意的两个特殊路径在mo.Thread中调用 setter 会立即处理状态更新并执行 stale 单元格在主线程的单元格执行之外调用 setter例如前端消息触发的 widget 回调或 async 任务时setter 单元格 ID 使用__external__哨兵值从而跳过自环self-loop预防逻辑下游单元格照常重跑。tests/_runtime/test_state.py 中的test_external_state_update与test_external_set_state_reruns_dependent_cell两个用例验证了这一行为。allow_self_loops 参数参数类型默认值作用valueT必填状态的初始值allow_self_loopsboolFalse为True时调用 setter 的单元格若也引用了 getter会被重跑默认为False防止自环测试用例 tests/_runtime/test_state.py 用两个对照用例验证了该参数test_no_self_loopsx state(); set_state(1)在同一个单元格中执行后x仍为0——调用 setter 的单元格不会被重跑test_allow_self_loops以allow_self_loopsTrue创建状态后x state(); if x 3: set_state(x 1)会不断自环递增最终x 3。响应式迭代与异常传播test_set_and_get_iterationtests/_runtime/test_state.py展示了状态更新的迭代效应单元格if x 5: set_state(x 1)每次运行都会触发其它引用 getter 的单元格如x state()重跑形成跨单元格的循环直到x 5停止。这正是 state 可以引入跨单元格循环 的含义——marimo 程序在静态层面仍是单元格 DAG有向无环图state 只是让 setter 在运行时挂钩进这个 DAG被调用时才触发额外计算因此必须小心避免死循环。同时tests/_runtime/test_state.py 的test_cancelled_not_run表明如果某个上游单元格抛错导致依赖链被取消即使下游单元格引用了 getter 也不会运行异常传播语义与普通响应式执行一致。将状态与 UI 元素结合on_change 回调每个 UI 元素都接受可选的on_change回调——一个接收元素新值并做任意处理的函数。你可以把 setter 放进on_change回调来修改状态。注意仅靠mo.ui就能完成大部分工作因为 marimo 会在交互时自动运行引用 UI 元素的单元格见 交互式指南。只有当on_change回调作为最后手段时才使用它示例一计数器下面几个单元格实现一个由两个按钮控制的计数器。虽然此例不用 state 也能实现可以试试但用 state 的实现更简洁。单元格 1导入import marimo as mo单元格 2创建状态与按钮get_counter, set_counter mo.state(0) increment mo.ui.button( labelincrement, on_changelambda _: set_counter(lambda v: v 1), ) decrement mo.ui.button( labeldecrement, on_changelambda _: set_counter(lambda v: v - 1), ) mo.hstack([increment, decrement], justifycenter)单元格 3展示当前值mo.md( f The counters current value is **{get_counter()}**! This cell runs automatically on button click, even though it doesnt reference either button. )这个例子完美诠释了响应式规则第三个单元格虽然不引用任何按钮只引用了 getterget_counter但每次点击按钮触发 setter它都会自动重跑。示例二联动元素tied elements这个例子展示如何让两个不同的 UI 元素互相绑定、值彼此依赖。不使用mo.state就无法实现。单元格 1导入import marimo as mo单元格 2创建共享状态get_x, set_x mo.state(0)单元格 3滑块驱动数字x mo.ui.slider( 0, 10, valueget_x(), on_changeset_x, label$x$: )单元格 4数字反向驱动滑块x_plus_one mo.ui.number( 1, 11, valueget_x() 1, on_changelambda v: set_x(v - 1), label$x 1$:, )单元格 5展示[x, x_plus_one]拖动滑块 →set_x被调用 → 引用get_x的数字元素单元格重跑x_plus_one显示x 1修改数字 →set_x(v - 1)被调用 → 引用get_x的滑块单元格重跑滑块回到对应位置。注意联动元素必须在不同单元格中创建因为在某个单元格内调用 setter 只会排队运行其它读取该状态的单元格不包括刚调用 setter 的那个单元格。警告可以用 state 在运行时跨单元格引入循环来联动 UI 元素但切勿引入无限循环。marimo 程序在静态层面仍被解析为单元格 DAGstate 不会改变这一点——请把 setter 理解为运行时挂钩只在被调用时触发额外计算。示例三TODO 列表下面几个单元格用 state 实现一个可增删的 TODO 列表演示了维护无法从内置 value 推导的历史状态这一核心场景。单元格 1导入import marimo as mo from dataclasses import dataclass单元格 2定义任务模型与状态dataclass class Task: name: str done: bool False get_tasks, set_tasks mo.state([]) task_added, set_task_added mo.state(False)单元格 3刷新文本框# Refresh the text box whenever a task is added task_added task_entry_box mo.ui.text(placeholdera task ...)task_added这一行是关键当set_task_added(True)被调用时此单元格会重跑从而重建文本框确保新增任务后输入框被清空。单元格 4添加/清除任务的逻辑与按钮def add_task(): if task_entry_box.value: set_tasks(lambda v: v [Task(task_entry_box.value)]) set_task_added(True) def clear_tasks(): set_tasks(lambda v: [task for task in v if not task.done]) add_task_button mo.ui.button( labeladd task, on_changelambda _: add_task(), ) clear_tasks_button mo.ui.button( labelclear completed tasks, on_changelambda _: clear_tasks() )单元格 5渲染任务复选框列表task_list mo.ui.array( [mo.ui.checkbox(valuetask.done, labeltask.name) for task in get_tasks()], labeltasks, on_changelambda v: set_tasks( lambda tasks: [Task(task.name, donev[i]) for i, task in enumerate(tasks)] ), )单元格 6组装界面inputs mo.hstack( [task_entry_box, add_task_button, clear_tasks_button], justifystart ) mo.vstack([inputs, task_list])点击 add task →set_tasks追加任务、set_task_added(True)触发文本框单元格重跑 →task_list单元格因引用get_tasks自动重跑用新任务列表重建复选框。勾选任务 →on_change回调把勾选状态写回 state → 列表单元格再次重跑。clear completed tasks 则通过函数式更新过滤掉已完成任务。整个流程展示了历史状态维护 双向联动的完整范式。使用状态的两个重要禁忌不要将 UI 元素存入状态marimo/_runtime/state.py 的 docstring 明确警告不要将marimo.ui元素存储在 state 中这会导致难以诊断的 bug。UI 元素本身是响应式对象放入状态会与 marimo 的元素生命周期管理产生冲突。只通过 setter 修改状态如 marimo/_runtime/state.py 所述永远不要直接修改状态只能通过其 setter 改变值。setter 内部在更新_value后会调用register_state_update通知运行时marimo/_runtime/state.py直接改值会绕过这一通知机制导致依赖单元格不会重跑。状态与普通脚本运行在 marimo 中笔记本既可以交互运行也可以作为普通 Python 脚本执行python notebook.py。从 marimo/_runtime/context/script_context.py 看脚本上下文同样维护了自己的state_registry和register_state_update因此mo.state在脚本模式下也能正常工作——只是没有前端交互来触发on_change回调而已。在脚本模式下创建State时若运行上下文尚未初始化ContextNotInitializedError会被静默捕获marimo/_runtime/state.py注册可能延迟到上下文就绪后完成。总结何时用、何时不用场景推荐方案单个 UI 元素驱动其它单元格直接用元素value属性 响应式执行不需要mo.state按钮点击等简单交互内置value即可参见 recipes.md单向派生的值响应式执行见 交互式指南不要用mo.state维护历史状态如 TODO 列表✅mo.state同步两个 UI 元素双向绑定✅mo.state元素必须在不同单元格创建跨单元格运行时循环✅mo.state小心死循环mo.state是 marimo 中功能强大但需要谨慎使用的工具。优先使用 UI 元素的内置value与响应式执行这一函数式范式仅在确实需要可变状态、双向同步或跨单元格循环时才引入mo.state并遵循只通过 setter 更新、不存储 UI 元素、谨防无限循环三条铁律。相关完整实现可进一步阅读 marimo/_runtime/state.py 与 marimo/_runtime/runtime.py行为验证可参考 tests/_runtime/test_state.py。【免费下载链接】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.state 同步 UI 元素与跨单元格状态
marimo 响应式状态详解使用 mo.state 同步 UI 元素与跨单元格状态【免费下载链接】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导读mo.state是 marimo 提供的可变响应式状态mutable reactive stateAPI它返回一对 getter/setter 函数允许你跨单元格维护可变状态并在状态被 setter 更新时自动触发所有读取该状态的单元格重新执行。本文将以 docs/api/state.md 与 docs/guides/state.md 为核心结合 marimo/_runtime/state.py 的源码实现与 tests/_runtime/test_state.py 的测试用例深入讲解mo.state的适用场景、完整用法、状态响应式规则、与 UI 元素的联动方式以及底层运行机制帮助你安全、正确地使用这一高级特性。先决条件你真的需要mo.state吗marimo 官方文档在介绍mo.state之前给出了两条醒目的警告先阅读交互式指南创建交互式元素指南 是学习本文的前置要求。这是一个高级主题超过 99% 的场景下你不需要也不应该使用mo.state因为它可能引入难以排查的 bug。UI 元素本身已经内置了状态——即它们的value属性。例如mo.ui.slider()的 value 是它在区间上的当前位置mo.ui.button()的 value 可以配置为点击计数或True/False切换。更重要的是绑定到全局变量的 UI 元素在被交互时会自动执行所有引用这些变量的单元格你只需读取value属性即可响应变化。这种函数式范式是 marimo 中响应 UI 交互的首选方式例如处理按钮点击根本不需要响应式状态参见 recipes.md 中的 working with buttons 部分。哪些迹象说明你可能需要mo.state根据 docs/guides/state.md只有出现以下需求时才考虑使用mo.state维护历史状态需要维护与某个 UI 元素相关的历史状态且该状态无法从其内置value推导例如用户曾经在表单里输入过的所有值同步两个不同的 UI 元素交互其中一个时另一个也随之联动例如两个元素互相控制跨单元格引入循环需要在运行时引入跨单元格的循环依赖。单向数据流场景下不要使用mo.statedocs/guides/state.md 特别强调如果只是想用一个元素的值去更新另一个元素单向数据流不应该使用mo.state而应使用 marimo 内置的响应式执行机制见 交互式指南。mo.state的价值在于双向绑定和可变状态而非单向派生。mo.state 基本用法getter 与 settermo.state(value, allow_self_loopsFalse)接收一个初始值创建一个状态对象并返回一个二元组getter 函数用于读取状态的当前值setter 函数用于更新状态的值。其函数签名定义于 marimo/_runtime/state.pydef state( value: T, allow_self_loops: bool False ) - tuple[State[T], Callable[[T], None]]:创建状态import marimo as mo get_count, set_count mo.state(0)注意使用mo.state()时必须将 state getter 赋值给全局变量这与 UI 元素的工作方式类似——只有通过全局变量引用的单元格才会被自动重跑。读取状态通过调用 getter 函数访问最新值get_count() # 0更新状态用新值直接覆盖set_count(1) # 现在 get_count() 返回 1基于当前值做增量更新时可以传入一个接收当前值、返回新值的函数set_count(lambda value: value 1)底层实现中SetFunctor.__call__marimo/_runtime/state.py会判断传入的参数是函数还是普通值若是函数types.MethodType或types.FunctionType则以当前值调用它得到新值否则直接赋值。self._state._value ( update(self._state._value) if isinstance(update, (types.MethodType, types.FunctionType)) else update )这意味着任何普通对象包括定义了__call__的实例都会被当作普通值存储而不会被调用——tests/_runtime/test_state.py 中的test_set_to_callable_object用例专门验证了这一点。注意永远不要直接修改状态的内部值只能通过 setter 改变它。源码中的State._value是私有字段绕过 setter 修改会破坏响应式触发机制。状态响应式规则setter 调用后发生了什么核心规则当在一个单元格中调用状态 setter 函数时marimo 会自动运行所有其他引用了该状态 getter 全局变量的单元格。这一规则有两个重要方面只有通过全局变量读取状态 getter 的单元格会被运行调用 setter 的那个单元格不会被重跑即使它引用了 getter——这是为了防止潜在的 bug。若要解除此限制允许调用者单元格被重跑请使用mo.state(value, allow_self_loopsTrue)创建状态。状态与 UI 元素高度相似交互 UI 元素时所有通过全局变量引用该元素的单元格会用新值自动运行同理通过 setter 更新状态时所有通过全局变量引用 getter 的单元格也会自动运行。实现原理StateRegistry 与运行时集成从源码结构看状态的注册与查找由StateRegistrymarimo/_runtime/state.py负责每个State实例在创建时向运行上下文的state_registry注册记录变量名 → State 弱引用的映射register方法register_scope会在单元格执行后扫描新定义的全局变量把其中的State实例纳入注册表retain_active_states按当前活跃变量清理注册表避免变量被删除后状态残留。每次 setter 调用后SetFunctor会调用ctx.register_state_update(self._state)。在 marimo/_runtime/runtime.py 中Kernel.register_state_update记录哪个状态被哪个单元格更新随后由_find_cells_for_statemarimo/_runtime/runtime.py扫描图中所有单元格的 refs找出引用了该状态对象的单元格 ID排除调用 setter 的单元格除非allow_self_loopsTrue将这些单元格标记为 stale 并触发重跑。值得注意的两个特殊路径在mo.Thread中调用 setter 会立即处理状态更新并执行 stale 单元格在主线程的单元格执行之外调用 setter例如前端消息触发的 widget 回调或 async 任务时setter 单元格 ID 使用__external__哨兵值从而跳过自环self-loop预防逻辑下游单元格照常重跑。tests/_runtime/test_state.py 中的test_external_state_update与test_external_set_state_reruns_dependent_cell两个用例验证了这一行为。allow_self_loops 参数参数类型默认值作用valueT必填状态的初始值allow_self_loopsboolFalse为True时调用 setter 的单元格若也引用了 getter会被重跑默认为False防止自环测试用例 tests/_runtime/test_state.py 用两个对照用例验证了该参数test_no_self_loopsx state(); set_state(1)在同一个单元格中执行后x仍为0——调用 setter 的单元格不会被重跑test_allow_self_loops以allow_self_loopsTrue创建状态后x state(); if x 3: set_state(x 1)会不断自环递增最终x 3。响应式迭代与异常传播test_set_and_get_iterationtests/_runtime/test_state.py展示了状态更新的迭代效应单元格if x 5: set_state(x 1)每次运行都会触发其它引用 getter 的单元格如x state()重跑形成跨单元格的循环直到x 5停止。这正是 state 可以引入跨单元格循环 的含义——marimo 程序在静态层面仍是单元格 DAG有向无环图state 只是让 setter 在运行时挂钩进这个 DAG被调用时才触发额外计算因此必须小心避免死循环。同时tests/_runtime/test_state.py 的test_cancelled_not_run表明如果某个上游单元格抛错导致依赖链被取消即使下游单元格引用了 getter 也不会运行异常传播语义与普通响应式执行一致。将状态与 UI 元素结合on_change 回调每个 UI 元素都接受可选的on_change回调——一个接收元素新值并做任意处理的函数。你可以把 setter 放进on_change回调来修改状态。注意仅靠mo.ui就能完成大部分工作因为 marimo 会在交互时自动运行引用 UI 元素的单元格见 交互式指南。只有当on_change回调作为最后手段时才使用它示例一计数器下面几个单元格实现一个由两个按钮控制的计数器。虽然此例不用 state 也能实现可以试试但用 state 的实现更简洁。单元格 1导入import marimo as mo单元格 2创建状态与按钮get_counter, set_counter mo.state(0) increment mo.ui.button( labelincrement, on_changelambda _: set_counter(lambda v: v 1), ) decrement mo.ui.button( labeldecrement, on_changelambda _: set_counter(lambda v: v - 1), ) mo.hstack([increment, decrement], justifycenter)单元格 3展示当前值mo.md( f The counters current value is **{get_counter()}**! This cell runs automatically on button click, even though it doesnt reference either button. )这个例子完美诠释了响应式规则第三个单元格虽然不引用任何按钮只引用了 getterget_counter但每次点击按钮触发 setter它都会自动重跑。示例二联动元素tied elements这个例子展示如何让两个不同的 UI 元素互相绑定、值彼此依赖。不使用mo.state就无法实现。单元格 1导入import marimo as mo单元格 2创建共享状态get_x, set_x mo.state(0)单元格 3滑块驱动数字x mo.ui.slider( 0, 10, valueget_x(), on_changeset_x, label$x$: )单元格 4数字反向驱动滑块x_plus_one mo.ui.number( 1, 11, valueget_x() 1, on_changelambda v: set_x(v - 1), label$x 1$:, )单元格 5展示[x, x_plus_one]拖动滑块 →set_x被调用 → 引用get_x的数字元素单元格重跑x_plus_one显示x 1修改数字 →set_x(v - 1)被调用 → 引用get_x的滑块单元格重跑滑块回到对应位置。注意联动元素必须在不同单元格中创建因为在某个单元格内调用 setter 只会排队运行其它读取该状态的单元格不包括刚调用 setter 的那个单元格。警告可以用 state 在运行时跨单元格引入循环来联动 UI 元素但切勿引入无限循环。marimo 程序在静态层面仍被解析为单元格 DAGstate 不会改变这一点——请把 setter 理解为运行时挂钩只在被调用时触发额外计算。示例三TODO 列表下面几个单元格用 state 实现一个可增删的 TODO 列表演示了维护无法从内置 value 推导的历史状态这一核心场景。单元格 1导入import marimo as mo from dataclasses import dataclass单元格 2定义任务模型与状态dataclass class Task: name: str done: bool False get_tasks, set_tasks mo.state([]) task_added, set_task_added mo.state(False)单元格 3刷新文本框# Refresh the text box whenever a task is added task_added task_entry_box mo.ui.text(placeholdera task ...)task_added这一行是关键当set_task_added(True)被调用时此单元格会重跑从而重建文本框确保新增任务后输入框被清空。单元格 4添加/清除任务的逻辑与按钮def add_task(): if task_entry_box.value: set_tasks(lambda v: v [Task(task_entry_box.value)]) set_task_added(True) def clear_tasks(): set_tasks(lambda v: [task for task in v if not task.done]) add_task_button mo.ui.button( labeladd task, on_changelambda _: add_task(), ) clear_tasks_button mo.ui.button( labelclear completed tasks, on_changelambda _: clear_tasks() )单元格 5渲染任务复选框列表task_list mo.ui.array( [mo.ui.checkbox(valuetask.done, labeltask.name) for task in get_tasks()], labeltasks, on_changelambda v: set_tasks( lambda tasks: [Task(task.name, donev[i]) for i, task in enumerate(tasks)] ), )单元格 6组装界面inputs mo.hstack( [task_entry_box, add_task_button, clear_tasks_button], justifystart ) mo.vstack([inputs, task_list])点击 add task →set_tasks追加任务、set_task_added(True)触发文本框单元格重跑 →task_list单元格因引用get_tasks自动重跑用新任务列表重建复选框。勾选任务 →on_change回调把勾选状态写回 state → 列表单元格再次重跑。clear completed tasks 则通过函数式更新过滤掉已完成任务。整个流程展示了历史状态维护 双向联动的完整范式。使用状态的两个重要禁忌不要将 UI 元素存入状态marimo/_runtime/state.py 的 docstring 明确警告不要将marimo.ui元素存储在 state 中这会导致难以诊断的 bug。UI 元素本身是响应式对象放入状态会与 marimo 的元素生命周期管理产生冲突。只通过 setter 修改状态如 marimo/_runtime/state.py 所述永远不要直接修改状态只能通过其 setter 改变值。setter 内部在更新_value后会调用register_state_update通知运行时marimo/_runtime/state.py直接改值会绕过这一通知机制导致依赖单元格不会重跑。状态与普通脚本运行在 marimo 中笔记本既可以交互运行也可以作为普通 Python 脚本执行python notebook.py。从 marimo/_runtime/context/script_context.py 看脚本上下文同样维护了自己的state_registry和register_state_update因此mo.state在脚本模式下也能正常工作——只是没有前端交互来触发on_change回调而已。在脚本模式下创建State时若运行上下文尚未初始化ContextNotInitializedError会被静默捕获marimo/_runtime/state.py注册可能延迟到上下文就绪后完成。总结何时用、何时不用场景推荐方案单个 UI 元素驱动其它单元格直接用元素value属性 响应式执行不需要mo.state按钮点击等简单交互内置value即可参见 recipes.md单向派生的值响应式执行见 交互式指南不要用mo.state维护历史状态如 TODO 列表✅mo.state同步两个 UI 元素双向绑定✅mo.state元素必须在不同单元格创建跨单元格运行时循环✅mo.state小心死循环mo.state是 marimo 中功能强大但需要谨慎使用的工具。优先使用 UI 元素的内置value与响应式执行这一函数式范式仅在确实需要可变状态、双向同步或跨单元格循环时才引入mo.state并遵循只通过 setter 更新、不存储 UI 元素、谨防无限循环三条铁律。相关完整实现可进一步阅读 marimo/_runtime/state.py 与 marimo/_runtime/runtime.py行为验证可参考 tests/_runtime/test_state.py。【免费下载链接】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），仅供参考