marimo 侧边栏布局实战用 mo.sidebar 构建多页面应用的导航骨架【免费下载链接】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导读在 marimo 中mo.sidebar是一个特殊的布局组件它能把单元格内容渲染到编辑器与运行应用App 模式的左侧栏位而不是单元格正文内从而为多页面应用、仪表盘和作品集类 Notebook 提供持久的导航骨架。本文以 docs/api/layouts/sidebar.md 为骨架结合marimo.sidebar的源码实现、官方冒烟测试 marimo/_smoke_tests/sidebar.py 与前端marimo-sidebar自定义元素sidebar-element.tsx完整讲解mo.sidebar的用法、参数、与mo.nav_menu/mo.routes的组合模式及其底层渲染原理。读完本文你将能独立搭建带分组导航、页脚与自定义宽度侧边栏的多页面 marimo 应用。一、认识 mo.sidebar单元格之外的特殊布局在默认布局下marimo 单元格的输出按顺序纵向排列。而mo.sidebar属于“特殊布局组件”它会把内容渲染在单元格旁边左侧的侧边栏区域而不是单元格下方它必须作为单元格的最后一个表达式才能正确显示源码 docstring 明确说明This component still needs to be the last expression in the cell同一个 Notebook 中可以多次调用mo.sidebar它们会按调用顺序依次显示源码注释You may use more than onemo.sidebar- they will be displayed in the order they are called它是持久性导航的最佳载体侧边栏常驻主体区域由mo.routes或其他内容动态切换非常适合把 marimo Notebook 组织成多页面应用参见 docs/api/layouts/routes.md。这些行为约束直接来自 marimo/_plugins/stateless/sidebar.py 中sidebar类的实现属于可验证的官方行为。1.1 从 API 文档中的标准示例看起sidebar.md 给出的最小可用示例如下app.cell def __(): mo.sidebar( [ mo.md(# marimo), mo.nav_menu( { #/home: f{mo.icon(lucide:home)} Home, #/about: f{mo.icon(lucide:user)} About, #/contact: f{mo.icon(lucide:phone)} Contact, Links: { https://twitter.com/marimo_io: Twitter, https://github.com/marimo-team/marimo: GitHub, }, }, orientationvertical, ), ] ) return这个例子同时覆盖了mo.sidebar的三种典型内容来源mo.md(...)渲染的 Markdown品牌标题# marimomo.nav_menu(...)生成的纵向导航菜单含一级链接与Links分组列表形式的多个子组件由vstack自动纵向堆叠。二、API 签名与参数详解根据 sidebar.py 的__init__签名def __init__( self, item: object, footer: object | None None, *, width: str | int | None None, ) - None三个参数的含义与内部处理逻辑如下参数类型默认值说明itemobject必填—侧边栏主体内容。字符串会被自动包装为mo.md(...)列表会被自动包装为vstack(...)纵向堆叠其余对象按 HTML 渲染footerobject可选None固定在侧边栏底部的内容。字符串自动转md列表自动转vstack最终与item一起以justifyspace-between排布widthstr/int可选标准宽度侧边栏展开时的宽度接受任意合法 CSS 宽度值如300px、20rem数值会自动转为字符串以便 JSON 序列化源码中的关键处理逻辑字符串自动包装if isinstance(item, str): item md.md(item)列表自动堆叠if isinstance(item, list): item vstack(item)footer存在时主体与页脚以两端对齐方式组合item vstack([item, footer], justifyspace-between)width非空时写入self._props[width] str(width)前端据此控制展开宽度。2.1 不受支持的链式方法mo.sidebar继承自ContainerHtml但明确禁用了部分链式 API。源码中以raise TypeError显式拒绝的方法包括.batch()、.center()、.right()、.left().callout()、.style()也就是说mo.sidebar(...).style(...)这类链式调用会直接抛错侧边栏宽度只能通过构造参数width控制。三、进阶用法footer 与 width 参数实战官方冒烟测试 marimo/_smoke_tests/sidebar.py 展示了比文档示例更完整的配置可复制到你的 Notebook 中直接运行import marimo __generated_with 0.15.5 app marimo.App(widthfull) app.cell def _(mo): mo.sidebar( [ mo.md(# marimo), mo.nav_menu( { #home: f{mo.icon(lucide:home)} Home, #about: f{mo.icon(lucide:user)} About, #contact: f{mo.icon(lucide:phone)} Contact, Links: { https://twitter.com/marimo_io: Twitter, https://github.com/marimo-team/marimo: GitHub, }, }, orientationvertical, ), ], footer[ mo.md( ### Footer - [Twitter](https://twitter.com/marimo_io) - [GitHub](https://github.com/marimo-team/marimo) ) ], width500px, ) return要点拆解页脚footerfooter接收一个包含mo.md的列表源码会自动将其vstack并置于侧边栏底部与主体justifyspace-between分离适合放版权信息、外部链接或版本号宽度widthwidth500px让侧边栏展开时占 500px。官方文档建议使用任意合法 CSS 宽度值如300px、20rem图标装饰链接标签中的mo.icon(lucide:home)以 Lucide 图标为菜单项增加视觉标识mo.icon是 marimo 内置图标 API见 docs/api 相关条目。四、与 mo.nav_menu 组合构建多页面导航侧边栏最常见的搭档是mo.nav_menu后者是 marimo 官方的导航菜单组件实现在 marimo/_plugins/stateless/nav_menu.py。其签名如下def nav_menu( menu: dict[str, JSONType], *, orientation: Literal[horizontal, vertical] horizontal, ) - Html4.1 菜单数据模型与校验规则nav_menu的菜单字典支持三级结构见_build_and_validate_menu的实现一级链接{/overview: Overview}键为 href值为字符串会被当作 Markdown 渲染分组子菜单{Sales: {/sales: Overview, ...}}嵌套一层字典带描述的链接{/sales/invoices: {label: Invoices, description: View invoices}}值必须是含label必填与description可选的字典。href 校验链接必须以/、#或http开头否则抛出ValueError: Invalid href: ...源码 nav_menu.py 的validate_href。因此Notebook 内页面路由用#/path如#/home外部站点用https://...如 Twitter、GitHub 链接。orientation 参数horizontal默认适合页面顶栏或vertical适合侧边栏。官方 docstring 中给出的子菜单示例可直接用于侧边栏nav_menu mo.nav_menu( { /overview: Overview, Sales: { /sales: Overview, /sales/invoices: { label: Invoices, description: View invoices, }, /sales/customers: { label: Customers, description: View customers, }, }, }, orientationvertical, )五、配合 mo.routes 实现页面切换侧边栏负责“导航骨架”页面内容切换则由mo.routes完成。官方文档 docs/api/layouts/routes.md 给出了完整的多页面组合import marimo app marimo.App() app.cell def __(): mo.sidebar( [ mo.md(# marimo), mo.nav_menu( { #/: f{mo.icon(lucide:home)} Home, #/about: f{mo.icon(lucide:user)} About, #/contact: f{mo.icon(lucide:phone)} Contact, Links: { https://twitter.com/marimo_io: Twitter, https://github.com/marimo-team/marimo: GitHub, }, }, orientationvertical, ), ] ) return app.cell def __(): mo.routes({ #/: mo.md(# Home), #/about: mo.md(# About), #/contact: mo.md(# Contact), mo.routes.CATCH_ALL: mo.md(# Home), }) return这里的关键配合点nav_menu的链接键#/、#/about、#/contact与mo.routes的路由键一一对应mo.routes.CATCH_ALL兜底未匹配路径示例中回落到 Home侧边栏导航常驻mo.routes依据#哈希路由动态渲染主体页面——这就是 marimo 多页面应用的推荐组织方式。六、底层原理从前端 marimo-sidebar 自定义元素看渲染机制mo.sidebar的 Python 端实现最终通过build_stateless_plugin(marimo-sidebar, props, text)生成 HTML见 sidebar.py 的_build_text。前端侧marimo 通过自定义 DOM 元素marimo-sidebar把子内容“传送到”侧边栏 React 组件中实现在 frontend/src/plugins/core/sidebar-element.tsx。从源码可以梳理出以下几点实现事实DOM 传送Portal机制marimo-sidebar元素自身display: none隐藏在connectedCallback中通过slotsController.mount({ name: SlotNames.SIDEBAR, ... })把子内容挂载到侧边栏插槽slot上从而把“单元格内的输出”渲染到编辑器/App 的侧边栏区域宽度同步元素读取data-width属性并写入全局sidebarAtomJotai 状态侧边栏展开时据此设置宽度syncWidth方法中JSON.parse(width)动态更新通过MutationObserver监听子节点、属性、文本变化内容更新时自动重新渲染侧边栏updateReactComponent。侧边栏的 React 呈现、折叠切换等 UI 逻辑位于 frontend/src/components/editor/renderers/vertical-layout/sidebar/含toggle.tsx、wrapped-with-sidebar.tsx、state.ts及单元测试 sidebar.test.tsx可以推断侧边栏在编辑模式与运行模式App 模式下均可用且支持折叠/展开交互。七、实践建议与注意事项位置约定mo.sidebar必须是单元格的最后一个表达式否则不会按预期显示在侧边栏多次调用需要多个侧边栏时可直接多次调用显示顺序与调用顺序一致宽度限制使用width设置宽度而非链式.style()后者会抛TypeError菜单校验nav_menu的 href 必须以/、#或http开头组内子项必须提供字符串标签或含label的字典否则抛ValueError页面组织多页面应用推荐mo.sidebarmo.nav_menu(orientationvertical)mo.routes三件套并配合mo.icon(lucide:...)提升导航可读性可验证的完整示例仓库自带的可运行冒烟测试位于 marimo/_smoke_tests/sidebar.py包含 footer、width、垂直/水平导航菜单等全部用法是学习与调试mo.sidebar的首选参考。【免费下载链接】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），仅供参考