marimo 查询参数Query Parameters完全指南用 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/marimomarimo 中的mo.query_params提供了一种将 URL 查询字符串与笔记本运行时状态双向绑定的能力既能读取 URL 中的键值对来初始化 UI 与应用状态也能在运行时把状态写回 URL从而实现可收藏、可分享、可回放的状态即链接体验。读完本文你将掌握mo.query_params的完整 API、基于 Pydantic 的参数校验与文档化方案以及如何结合 FastAPI 挂载让查询参数进入自动生成的 API 文档为部署可交互应用打下基础。查询参数是什么URL 即状态查询参数Query Parameters是追加在 URL 末尾的键值对形如?key1value1key2value2用于向服务器传递数据或定制一次请求。在 marimo 中它们还有更特殊的意义应用以marimo run作为 Web 应用运行时URL 中的查询参数会进入笔记本运行时可以通过mo.query_params读取反过来你也可以通过mo.query_params设置查询参数把应用的当前状态持久化到 URL 中用于书签收藏或分享某一份特定状态的笔记本/应用。换句话说查询参数是 marimo 应用天然的URL 状态层——用户刷新页面、把链接发给他人、或从收藏夹重新打开时应用可以依据 URL 恢复出同样的界面状态。读取查询参数像字典一样使用在任意单元格中调用mo.query_params()即可拿到当前 URL 的查询参数对象import marimo as mo query_params mo.query_params()在 runtime.py 中该函数直接返回当前运行时上下文中的QueryParams实例其底层类型定义在 params.py本质是一个继承自State的可变对象。你可以像操作字典一样与它交互# 读取key 不存在时返回默认值 query_params.get(search) # str | list[str] | None query_params.get(search, 默认值) # 带默认值 query_params[search] # 等价于 get(key) search in query_params # 键是否存在 len(query_params) # 参数个数 # 多值参数 query_params.get_all(tags) # 总是返回 list[str]不存在时返回 []关于返回值源码 params.py 给出了明确约定单个值时返回str多个值时返回list[str]get_all则无条件返回列表便于统一处理多选类参数。序列化后的类型定义为SerializedQueryParams dict[str, ListOrValue[str]]见 commands.py。写入查询参数让状态变得可分享mo.query_params更强大的能力在于写入——对返回对象的任何修改都会被同步到前端 URL且引用它的其他单元格会自动重新运行它继承自响应式State。源码中每次写入都会通过broadcast_notification向浏览器广播一条QueryParamsSetNotification/QueryParamsAppendNotification/QueryParamsDeleteNotification/QueryParamsClearNotification定义见 notification.py从而驱动前端地址栏更新与下游单元格重算。常用的写入操作如下# 1. 设置/覆盖单个参数 query_params[mode] dark query_params.set(page, 3) # 与上方等价 # 2. 追加值到列表参数不存在则自动创建 query_params.append(tag, ml) # 3. 删除参数 del query_params[mode] # 删除整个键 query_params.remove(tag) # 删除整个键 query_params.remove(tag, ml) # 只从列表中移除某个值 # 4. 清空所有参数 query_params.clear()需要注意两个由 params.py 定义的边界行为将值设为None或空列表[]等价于删除该键底层广播的是query-params-delete操作set总是覆盖旧值append则把新值追加进列表若原值是单个str会先升级为双元素列表。这些行为在 test_query_params.py 中有完整覆盖例如test_setitem_null、test_append、test_remove分别验证了赋空即删、追加语义和按值删除的广播消息。一个完整的双向同步示例官方文档 runtime.py 的 docstring 给出了文本框内容 ↔ URL 参数双向同步的经典写法# 单元格 1建立 query_params 引用 query_params mo.query_params() # 单元格 2文本框初值来自 URL用户输入写回 URL search mo.ui.text( valuequery_params[search] or , on_changelambda value: query_params.set(search, value), ) search# 单元格 3响应式写回——开关状态直接存入 URL toggle mo.ui.switch(labelToggle me) toggle query_params[is_enabled] toggle.value当用户移动滑块、切换开关或编辑文本时URL 同步变化把该 URL 发给别人或收藏起来对方打开后即可看到完全一致的界面状态。用 Pydantic 模型校验并文档化查询参数查询参数最常见的落地场景之一是用它设置 UI 元素的初始状态。而把查询参数传入 Pydantic 模型可以一举两得既自动校验参数类型与取值范围又通过模型字段定义让参数可被文档化。RGB 颜色初始化示例以下是 query_params.md 中给出的完整示例定义 RGB 三通道与一条消息的模型从 URL 查询参数直接构造模型实例再用模型字段初始化三个滑块的初始值。import marimo as mo from pydantic import BaseModel, Field class MyModel(BaseModel): r: int Field(28, ge0, le255, descriptionRed Channel) g: int Field(115, ge0, le255, descriptionGreen Channel) b: int Field(97, ge0, le255, descriptionBlue Channel) message: str Field(br, descriptionSome text) model MyModel(**mo.query_params().to_dict()) # UI with initial state from query params r_slider mo.ui.slider(start0, stop255, step1, labelR, valuemodel.r) g_slider mo.ui.slider(start0, stop255, step1, labelG, valuemodel.g) b_slider mo.ui.slider(start0, stop255, step1, labelB, valuemodel.b)在下一个单元格中渲染 UI并基于模型字段生成动态样式bg_color frgb({r_slider.value},{g_slider.value},{b_slider.value}) mo.vstack([ r_slider, g_slider, b_slider, mo.Html(model.message bg_color).style(background_colorbg_color, text_aligncenter) ])这里的关键一步是mo.query_params().to_dict()——它把查询参数转为普通dict[str, str | list[str]]实现见 params.py从而可以用**解包直接喂给 Pydantic 模型。URL 中的?r255g0b0message...会在打开页面时完成类型转换、范围校验ge0, le255并作为滑块初值。若用户通过 URL 传入了非法值如r300Pydantic 的校验逻辑会拒绝该值并回退到默认值从而保证应用不被脏参数破坏。关于被忽略的键从源码 params.py 可以看到QueryParams定义了IGNORED_KEYS {access_token, refresh_token, session_id}。这意味着带有鉴权敏感信息的查询参数会被运行时忽略避免令牌类密钥意外流入笔记本状态——在把查询参数直接映射进模型或写回 URL 时这一内置保护值得留意。结合 FastAPI 挂载让模型进入 API 文档当使用create_asgi_app把 marimo 应用挂载到 FastAPI 时查询参数的 Pydantic 模型可以进一步成为主应用 API 文档的一部分。在 programmatically.md 中官方给出了先用 FastAPI 端点做模型校验再重定向到 marimo 端点的模式# src/main.py from fastapi import FastAPI, Request, Query from fastapi.responses import RedirectResponse from marimo import create_asgi_app from pathlib import Path from pydantic import BaseModel, Field from typing import Annotated, Literal from urllib.parse import urlencode app FastAPI() class FilterParams(BaseModel): limit: int Field(100, gt0, le100) offset: int Field(0, ge0) order_by: Literal[created_at, updated_at] created_at tags: list[str] [] app.get(/items) async def marimo_items( request: Request, filter_query: Annotated[FilterParams, Query()] ): query_params urlencode(filter_query.model_dump(), doseqTrue) return RedirectResponse(urlf/items/?{query_params}) server create_asgi_app(include_codeTrue, quietFalse) notebooks_dir Path(__file__).parent.parent / notebooks for filename in notebooks_dir.iterdir(): if filename.suffix .py: app_name filename.stem server server.with_app(pathf/{app_name}, rootfilename) app.mount(/, server.build())这段代码的流程是用户访问/items?limit20order_byupdated_at→ FastAPI 用FilterParams完成声明、校验与文档化 → 校验通过后经urlencode(..., doseqTrue)保留列表语义重新编码并 302 重定向到 marimo 挂载端点 → 笔记本内再通过mo.query_params()读取到同一份已校验的参数。这样既获得了 Swagger/OpenAPI 中自动生成的参数说明又保证了进入笔记本的数据一定是合法的。mo.cli_args不可被用户控制的参数与查询参数互补的另一个入口是mo.cli_args它用于访问启动笔记本时通过命令行传入的参数适用于不应当由用户控制的配置——例如内部密钥、环境标识、批处理任务编号等。import marimo as mo cli_args mo.cli_args() cli_args.get(data_path) # 读取命令行传入的参数从源码实现看CLIArgs与QueryParams的读取 API 高度一致get/get_all/__getitem__/__contains__/to_dict等见 params.py但有一个关键区别CLIArgs是只读的——对其执行params[key] value或del params[key]会抛出TypeError由 test_query_params.py 的TestCLIArgs用例验证。它的职责是注入不可变配置而把可变状态留给查询参数。更多命令行用法可参考 CLI 参数文档。底层机制一览综合源码mo.query_params的完整运行链路可以概括为序列化边界查询参数以dict[str, str | list[str]]形式在前后端之间传递见 commands.py单值与多值通过str/list[str]区分运行时注入mo.query_params()从当前内核运行时上下文取出QueryParams实例kernel_context.py 与 script_context.py 均暴露该属性笔记本与脚本模式行为一致响应式通知任何写入操作都会广播对应的query-params-set/append/delete/clear通知notification.py驱动前端 URL 更新与下游单元格重算——这也是URL 即状态能自动生效的根本原因安全过滤access_token、refresh_token、session_id三个敏感键被内置忽略params.py。典型应用场景总结可分享视图筛选条件、当前页码、图表配置写入 URL任何人打开同一链接即复现相同结果书签恢复用户刷新/收藏后应用自动回到上次状态UI 初值注入用 Pydantic 模型解析?r255g0b0初始化滑块、下拉框等控件且参数非法时自动回退默认值API 化部署FastAPI 挂载场景下查询参数模型自动进入 OpenAPI 文档实现校验 文档 状态传递三合一内部配置与mo.cli_args配合把用户可控的状态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/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 marimo 查询参数（Query Parameters）完全指南：用 URL 状态驱动响应式应用
marimo 查询参数Query Parameters完全指南用 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/marimomarimo 中的mo.query_params提供了一种将 URL 查询字符串与笔记本运行时状态双向绑定的能力既能读取 URL 中的键值对来初始化 UI 与应用状态也能在运行时把状态写回 URL从而实现可收藏、可分享、可回放的状态即链接体验。读完本文你将掌握mo.query_params的完整 API、基于 Pydantic 的参数校验与文档化方案以及如何结合 FastAPI 挂载让查询参数进入自动生成的 API 文档为部署可交互应用打下基础。查询参数是什么URL 即状态查询参数Query Parameters是追加在 URL 末尾的键值对形如?key1value1key2value2用于向服务器传递数据或定制一次请求。在 marimo 中它们还有更特殊的意义应用以marimo run作为 Web 应用运行时URL 中的查询参数会进入笔记本运行时可以通过mo.query_params读取反过来你也可以通过mo.query_params设置查询参数把应用的当前状态持久化到 URL 中用于书签收藏或分享某一份特定状态的笔记本/应用。换句话说查询参数是 marimo 应用天然的URL 状态层——用户刷新页面、把链接发给他人、或从收藏夹重新打开时应用可以依据 URL 恢复出同样的界面状态。读取查询参数像字典一样使用在任意单元格中调用mo.query_params()即可拿到当前 URL 的查询参数对象import marimo as mo query_params mo.query_params()在 runtime.py 中该函数直接返回当前运行时上下文中的QueryParams实例其底层类型定义在 params.py本质是一个继承自State的可变对象。你可以像操作字典一样与它交互# 读取key 不存在时返回默认值 query_params.get(search) # str | list[str] | None query_params.get(search, 默认值) # 带默认值 query_params[search] # 等价于 get(key) search in query_params # 键是否存在 len(query_params) # 参数个数 # 多值参数 query_params.get_all(tags) # 总是返回 list[str]不存在时返回 []关于返回值源码 params.py 给出了明确约定单个值时返回str多个值时返回list[str]get_all则无条件返回列表便于统一处理多选类参数。序列化后的类型定义为SerializedQueryParams dict[str, ListOrValue[str]]见 commands.py。写入查询参数让状态变得可分享mo.query_params更强大的能力在于写入——对返回对象的任何修改都会被同步到前端 URL且引用它的其他单元格会自动重新运行它继承自响应式State。源码中每次写入都会通过broadcast_notification向浏览器广播一条QueryParamsSetNotification/QueryParamsAppendNotification/QueryParamsDeleteNotification/QueryParamsClearNotification定义见 notification.py从而驱动前端地址栏更新与下游单元格重算。常用的写入操作如下# 1. 设置/覆盖单个参数 query_params[mode] dark query_params.set(page, 3) # 与上方等价 # 2. 追加值到列表参数不存在则自动创建 query_params.append(tag, ml) # 3. 删除参数 del query_params[mode] # 删除整个键 query_params.remove(tag) # 删除整个键 query_params.remove(tag, ml) # 只从列表中移除某个值 # 4. 清空所有参数 query_params.clear()需要注意两个由 params.py 定义的边界行为将值设为None或空列表[]等价于删除该键底层广播的是query-params-delete操作set总是覆盖旧值append则把新值追加进列表若原值是单个str会先升级为双元素列表。这些行为在 test_query_params.py 中有完整覆盖例如test_setitem_null、test_append、test_remove分别验证了赋空即删、追加语义和按值删除的广播消息。一个完整的双向同步示例官方文档 runtime.py 的 docstring 给出了文本框内容 ↔ URL 参数双向同步的经典写法# 单元格 1建立 query_params 引用 query_params mo.query_params() # 单元格 2文本框初值来自 URL用户输入写回 URL search mo.ui.text( valuequery_params[search] or , on_changelambda value: query_params.set(search, value), ) search# 单元格 3响应式写回——开关状态直接存入 URL toggle mo.ui.switch(labelToggle me) toggle query_params[is_enabled] toggle.value当用户移动滑块、切换开关或编辑文本时URL 同步变化把该 URL 发给别人或收藏起来对方打开后即可看到完全一致的界面状态。用 Pydantic 模型校验并文档化查询参数查询参数最常见的落地场景之一是用它设置 UI 元素的初始状态。而把查询参数传入 Pydantic 模型可以一举两得既自动校验参数类型与取值范围又通过模型字段定义让参数可被文档化。RGB 颜色初始化示例以下是 query_params.md 中给出的完整示例定义 RGB 三通道与一条消息的模型从 URL 查询参数直接构造模型实例再用模型字段初始化三个滑块的初始值。import marimo as mo from pydantic import BaseModel, Field class MyModel(BaseModel): r: int Field(28, ge0, le255, descriptionRed Channel) g: int Field(115, ge0, le255, descriptionGreen Channel) b: int Field(97, ge0, le255, descriptionBlue Channel) message: str Field(br, descriptionSome text) model MyModel(**mo.query_params().to_dict()) # UI with initial state from query params r_slider mo.ui.slider(start0, stop255, step1, labelR, valuemodel.r) g_slider mo.ui.slider(start0, stop255, step1, labelG, valuemodel.g) b_slider mo.ui.slider(start0, stop255, step1, labelB, valuemodel.b)在下一个单元格中渲染 UI并基于模型字段生成动态样式bg_color frgb({r_slider.value},{g_slider.value},{b_slider.value}) mo.vstack([ r_slider, g_slider, b_slider, mo.Html(model.message bg_color).style(background_colorbg_color, text_aligncenter) ])这里的关键一步是mo.query_params().to_dict()——它把查询参数转为普通dict[str, str | list[str]]实现见 params.py从而可以用**解包直接喂给 Pydantic 模型。URL 中的?r255g0b0message...会在打开页面时完成类型转换、范围校验ge0, le255并作为滑块初值。若用户通过 URL 传入了非法值如r300Pydantic 的校验逻辑会拒绝该值并回退到默认值从而保证应用不被脏参数破坏。关于被忽略的键从源码 params.py 可以看到QueryParams定义了IGNORED_KEYS {access_token, refresh_token, session_id}。这意味着带有鉴权敏感信息的查询参数会被运行时忽略避免令牌类密钥意外流入笔记本状态——在把查询参数直接映射进模型或写回 URL 时这一内置保护值得留意。结合 FastAPI 挂载让模型进入 API 文档当使用create_asgi_app把 marimo 应用挂载到 FastAPI 时查询参数的 Pydantic 模型可以进一步成为主应用 API 文档的一部分。在 programmatically.md 中官方给出了先用 FastAPI 端点做模型校验再重定向到 marimo 端点的模式# src/main.py from fastapi import FastAPI, Request, Query from fastapi.responses import RedirectResponse from marimo import create_asgi_app from pathlib import Path from pydantic import BaseModel, Field from typing import Annotated, Literal from urllib.parse import urlencode app FastAPI() class FilterParams(BaseModel): limit: int Field(100, gt0, le100) offset: int Field(0, ge0) order_by: Literal[created_at, updated_at] created_at tags: list[str] [] app.get(/items) async def marimo_items( request: Request, filter_query: Annotated[FilterParams, Query()] ): query_params urlencode(filter_query.model_dump(), doseqTrue) return RedirectResponse(urlf/items/?{query_params}) server create_asgi_app(include_codeTrue, quietFalse) notebooks_dir Path(__file__).parent.parent / notebooks for filename in notebooks_dir.iterdir(): if filename.suffix .py: app_name filename.stem server server.with_app(pathf/{app_name}, rootfilename) app.mount(/, server.build())这段代码的流程是用户访问/items?limit20order_byupdated_at→ FastAPI 用FilterParams完成声明、校验与文档化 → 校验通过后经urlencode(..., doseqTrue)保留列表语义重新编码并 302 重定向到 marimo 挂载端点 → 笔记本内再通过mo.query_params()读取到同一份已校验的参数。这样既获得了 Swagger/OpenAPI 中自动生成的参数说明又保证了进入笔记本的数据一定是合法的。mo.cli_args不可被用户控制的参数与查询参数互补的另一个入口是mo.cli_args它用于访问启动笔记本时通过命令行传入的参数适用于不应当由用户控制的配置——例如内部密钥、环境标识、批处理任务编号等。import marimo as mo cli_args mo.cli_args() cli_args.get(data_path) # 读取命令行传入的参数从源码实现看CLIArgs与QueryParams的读取 API 高度一致get/get_all/__getitem__/__contains__/to_dict等见 params.py但有一个关键区别CLIArgs是只读的——对其执行params[key] value或del params[key]会抛出TypeError由 test_query_params.py 的TestCLIArgs用例验证。它的职责是注入不可变配置而把可变状态留给查询参数。更多命令行用法可参考 CLI 参数文档。底层机制一览综合源码mo.query_params的完整运行链路可以概括为序列化边界查询参数以dict[str, str | list[str]]形式在前后端之间传递见 commands.py单值与多值通过str/list[str]区分运行时注入mo.query_params()从当前内核运行时上下文取出QueryParams实例kernel_context.py 与 script_context.py 均暴露该属性笔记本与脚本模式行为一致响应式通知任何写入操作都会广播对应的query-params-set/append/delete/clear通知notification.py驱动前端 URL 更新与下游单元格重算——这也是URL 即状态能自动生效的根本原因安全过滤access_token、refresh_token、session_id三个敏感键被内置忽略params.py。典型应用场景总结可分享视图筛选条件、当前页码、图表配置写入 URL任何人打开同一链接即复现相同结果书签恢复用户刷新/收藏后应用自动回到上次状态UI 初值注入用 Pydantic 模型解析?r255g0b0初始化滑块、下拉框等控件且参数非法时自动回退默认值API 化部署FastAPI 挂载场景下查询参数模型自动进入 OpenAPI 文档实现校验 文档 状态传递三合一内部配置与mo.cli_args配合把用户可控的状态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/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考