marimo Islands 实战指南：在任意 HTML 页面中嵌入响应式 Python 交互单元

marimo Islands 实战指南在任意 HTML 页面中嵌入响应式 Python 交互单元【免费下载链接】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 islands 是 marimo 提供的一种HTML 岛屿机制它允许你把单个 notebook 单元格cell的代码与输出渲染成一段独立的 HTML 片段嵌入到博客、文档站、教程等任意网页中页面加载后由 marimo 的响应式运行时基于 Pyodide 的浏览器端运行时接管并使其可交互。本文以仓库中的示例文档docs/guides/island_example.md为主体结合marimo/_islands/_island_generator.py等源码完整讲解 islands 的 HTML 结构、head 资源引入、MarimoIslandGenerator生成 API、响应式/非响应式行为以及本地开发与构建流程读完你就能在自己的静态站点中落地交互式 Python 内容。什么是 marimo islandsmarimo islands 是 island architecture岛屿架构思想在数据笔记本领域的实现把页面视为一片海洋其中散布的每个岛屿都是一个独立渲染、可独立交互的 marimo 单元格。与 marimo 的应用模式app mode不同island 模式没有顶层 app 外壳也不访问父页面的 HTML——每个 island 携带自己的静态输出与代码由运行时按需激活。仓库 前端 islands 开发文档 对它的定义是marimo islands 是一种渲染 HTML 岛屿 的方式每个岛屿包含静态输出和代码。它在 marimo 中主要服务于两类场景创建交互式博客文章、教程与教学材料作为构建静态站点生成器SSG或文档工具集成的底层构件。从源码结构看marimo 在后端把每个单元格编译为一段标准 HTML 片段同时在marimo/_schemas/islands.py中定义了配套的 JSON payloadschemaVersion、appId、cells列表浏览器端的 islands 运行时见 frontend 源码目录 相关实现负责用该 payload 水合hydrate页面使已渲染的静态输出重新获得响应式能力。需要注意的是仓库中 webassembly_html.md 明确标注 islands 目前属于早期特性PreviewAPI 大概率不会变动但在被视为稳定之前仍有一些改进计划。示例文档展示了什么仓库中的 island_example.md 本身就是一篇由 islands 驱动的活文档它的正文里嵌入了三个真实的 island分别演示了三类典型用法导入单元格import marimo as mo为后续单元格准备运行时交互 UI 单元格一个mo.ui.slider(0, 10, value2)滑块初始值为 2响应式输出单元格mo.md(fHello, islands! {️ * slider.value})其输出随滑块值实时变化并附带一个只读的代码编辑器展示源码。这三个单元格构成了一个最小但完整的响应式依赖链滑块 → 输出文本充分体现了 islands 之间依然保持 marimo 的响应式数据流。Island 的 HTML 结构逐层拆解示例文档末尾的 See the HTML 折叠块给出了渲染后的完整 HTML。一个 island 在 DOM 中是一个自定义元素marimo-island核心结构如下以滑块单元格为例marimo-island>!-- 1. marimo islands 运行时 JS 与样式 -- script typemodule srchttps://cdn.jsdelivr.net/npm/marimo-team/islands0.5.0/dist/main.js/script link hrefhttps://cdn.jsdelivr.net/npm/marimo-team/islands0.5.0/dist/style.css relstylesheet crossoriginanonymous / !-- 2. 字体Fira Mono / Lora / PT Sans带 preconnect 优化 -- link relpreconnect hrefhttps://fonts.googleapis.com / link relpreconnect hrefhttps://fonts.gstatic.com crossorigin / link hrefhttps://fonts.googleapis.com/css2?familyFiraMono:wght400;500;700amp;familyLoraamp;familyPTSans:wght400;700amp;displayswap relstylesheet / !-- 3. KaTeX 样式渲染 Markdown 中的 LaTeX 数学公式 -- link relstylesheet hrefhttps://cdn.jsdelivr.net/npm/katex0.16.10/dist/katex.min.css integritysha384-wcIxkf4k558AjM3Yz3BBFQUbk/zgIYC2R0QpeeYbTwlBVMrlgLqwRjRtGZiK7ww crossoriginanonymous /手动引入还是自动生成虽然可以像示例文档那样手写这些标签但更推荐用生成器自动产出。后端 render_head() 方法正是用来生成这套 head 内容的它会按当前 marimo 版本version_override参数可覆盖拼接https://cdn.jsdelivr.net/npm/marimo-team/islands{version}/dist/main.js与style.cssGoogle Fonts 的 preconnect 与字体表源码注释解释了为何字体不打包进 CSS以及嵌入式页面使用displayswap以保证字体加载兼容性KaTeX 样式表一个隐藏的marimo-filename hidden标记元素marimo_tags。如果传入_development_urlTrue则改用本地开发服务器默认http://localhost:5174的/dist/main.js与/dist/style.css便于在开发模式下热更新调试 islands 前端。用 MarimoIslandGenerator 生成岛屿页面仓库 _island_generator.py 是 islands 后端的核心MarimoIslandGenerator的设计目标是让其他 SSG 框架用 marimo-islands 把 Python 代码转成 HTML官方推荐的通用流程是把所有代码片段加入生成器build()构建应用用渲染出的 HTML 替换原代码片段把 head 内容放入head标签。方式一从代码片段生成add_code buildimport asyncio import sys from marimo import MarimoIslandGenerator # Windows 下需要设置事件循环策略 if sys.platform win32: asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) async def main(): generator MarimoIslandGenerator() block1 generator.add_code(import marimo as mo) block2 generator.add_code(mo.md(Hello, islands!)) # 构建应用内部会实际执行一次 notebook捕获每个单元格的输出 app await generator.build() output f html head {generator.render_head()} /head body {block1.render(display_outputFalse)} {block2.render()} /body /html print(output) output_file output.html with open(output_file, w, encodingutf-8) as f: f.write(output) if __name__ __main__: asyncio.run(main())这里两个关键调用值得展开add_code()接收一段 Python 源码内部先做dedent除非is_rawTrue然后分配单元格 ID、用compile_cell编译、注册到内部 App最后返回一个MarimoIslandStub。它的四个参数正是上一节提到的三个开关加上is_rawdisplay_code默认False是否在 HTML 中展示代码display_output默认True是否在 HTML 中包含输出is_reactive默认True该代码块是否随 Pyodide 在浏览器中运行is_raw默认False是否跳过 dedent 原样处理代码。build()是异步方法且只能调用一次再次调用会抛出ValueError(You can only call build() once)。它内部通过run_notebook真正执行一次 notebook拿到SessionView与每个单元格的CellOutput随后每个 stub 才能通过stub.output拿到执行结果。这解释了为什么必须在add_code全部完成后、render()之前调用build()。MarimoIslandStub.render()是产出 HTML 的最终入口它支持在调用时以参数覆盖构造时的默认值例如block1.render(display_outputFalse)并且有一个as_rawTrue模式此时会去掉marimo-island包装、直接输出解码后的原始值主要用于无 JS 场景如 PDF 导出。方式二从 notebook 文件生成from_file如果你的内容已经是一个 marimo notebook.py文件可以直接导入from marimo import MarimoIslandGenerator # 从 notebook 文件创建生成器每个单元格对应一个 stub generator MarimoIslandGenerator.from_file(./notebook-name.py, display_codeFalse) # 不 build 也可以渲染 HTML基础渲染可用但单元格未真正执行 html generator.render_html(include_init_islandFalse) print(html) output_file output.html with open(output_file, w, encodingutf-8) as f: f.write(html)from_file() 内部通过load_notebook读取 notebook遍历cell_manager.cell_data()把每个单元格的代码逐个add_code进来并保留 notebook 的 App 配置如width等布局设置。一个值得注意的细节是它会记录源文件绝对路径_source_filename这样单元格内引用__file__或mo.notebook_dir()时解析到的是 notebook 文件本身而非宿主进程避免后续chdir改变路径语义。一键产出完整 HTMLrender_html如果不想自己拼装页面骨架render_html() 可以一步生成完整的独立 HTML 文档含!doctype html、head、title与body。它的可选参数包括参数作用version_override指定 CDN 加载的 marimo islands JS/CSS 版本_development_url为True或字符串时改用本地 islands JS默认http://localhost:5174include_init_island是否在 body 最前面加入初始化加载中的旋转指示岛include_payload是否在末尾追加 JSON payload 脚本标签用于水合max_width/margin/style控制包裹所有 island 的容器 div 的样式其中max_width未指定时会根据 notebook 配置自动推断width为compact或normal时为740pxmedium时为1110px否则为none。页面标题则取app_title配置未设置时回退为app_id。响应式与非响应式data-reactive 的语义data-reactivetrue是 island 交互性的总开关。在 _island_generator.py 中通过add_code(..., is_reactiveFalse)添加的单元格渲染时会得到data-reactivefalse通过from_file导入时_disabled_cell_ids()会结合单元格的 disabled 状态与数据流图DirectedGraph.is_disabled自动把被禁用的单元格标记为非响应式非响应式 island 的marimo-cell-code内容为空字符串uri_encode_component(self.code) if resolved_is_reactive else 即完全不向浏览器暴露代码。使用建议非响应式岛适合昂贵的计算或纯静态内容——它在服务端执行一次、输出固化不随其他岛变化而重新运行也不消耗浏览器端运行时资源。响应式岛则构成依赖网络如示例文档中滑块slider与文本mo.md(fHello, islands! {️ * slider.value})之间的联动调整滑块时下游岛在浏览器内即时重算。初始化加载岛init island由于岛屿运行时依赖 Pyodide 在浏览器中加载 Python 解释器首次加载需要时间。为此 render_init_island() 会生成一个特殊的静态岛一个旋转加载动画 Initializing... 文字data-reactivefalse作为 body 的第一个元素插入。它的职责是在 Pyodide 就绪前展示加载状态避免页面出现空白运行时初始化完成后自动消失把舞台交给真正的岛屿。如果不想显示加载动画例如页面以静态内容为主、不依赖水合可以在render_html(include_init_islandFalse)中关闭它。Payload 水合机制当include_payloadTrue时页面末尾会追加一个 JSON 脚本标签类型为application/vnd.marimo.islandsjson常量定义见 marimo/_schemas/islands.pyscript typeapplication/vnd.marimo.islandsjson{schemaVersion:1,appId:main,cells:[{cellId:cell-1,code:mo.md(Hello, islands!),outputHtml:\u003cspan\u003eHello, islands!\u003c/span\u003e,outputMimetype:text/markdown,reactive:true,displayCode:false,displayOutput:true}]}/script每个单元格的 payload 包含cellId、code、outputHtml、outputMimetype、reactive、displayCode、displayOutput七个字段见 MarimoIslandCellPayload。工作方式为DOM 提供可见的 island 槽位payload 提供运行时的单元格代码与输出元数据运行时据此水合页面。仓库 webassembly_html.md 特别提醒如果你对生成的 HTML 做后处理务必原样保留这个 JSON 脚本标签及其内容否则水合会失败。JSON 字符串中的 HTML 敏感字符在写入脚本标签前会被转义。演示站点的源码级实现islands 是如何自举的仓库中的 frontend/islands/generate.py 是用 islands 生成 islands 演示页面的自举示例它用MarimoIslandGenerator.add_code()声明了 30 多个示例岛Getting Started、Basic UI Components、Advanced Components、Data Display、Layout Composition、Island Features、Error Handling 七大类覆盖滑块、按钮、文本输入、下拉框、复选框、单选、数字输入、多选、区间滑块、Tabs、代码编辑器、表格、Markdown/LaTeX、表单、display_code/is_reactive组合以及错误显示等全部常见能力。运行方式# 生成带 CDN 链接的正式版 HTML默认用于部署 uv run ./islands/generate.py islands/__demo__/index.html # 本地生产构建测试 MODElocal uv run ./islands/generate.py islands/__demo__/index.html # Vite 开发模式pnpm dev:islands 会自动完成 MODEdev uv run ./islands/generate.py islands/__demo__/index.html生成器依据MODE环境变量选择三种脚本注入方式get_script_tagscdn使用generator.render_head()输出正式 CDN 资源local指向本地生产构建http://127.0.0.1:8001/main.jsdev注入 Vite 客户端与 React Refresh 全局钩子指向/src/core/islands/main.ts源码入口。生成的演示产物见 frontend/islands/demo/index.html其中甚至包含一个故意触发ModuleNotFoundError的岛用来展示错误如何在岛内以 MIME 渲染器呈现。此外generate.py 底部还有一个 Tailwind CSS 隔离测试区位于.marimo容器之外的样式不受全局 Tailwind 影响而容器内的样式含.dark模式会被应用——这印证了 island 架构不访问父页面 HTML、样式局部化的设计。本地开发与生产构建仓库 frontend/islands/development.md 给出了完整的开发闭环# 快速启动演示自动生成 demo HTML 并启动带 HMR 的 Vite dev server # 同时监听 generate.py 变更自动重载 pnpm dev:islands # 使用预构建的 marimo wheel免去本地编译 VITE_WASM_MARIMO_PREBUILT_WHEELtrue pnpm dev:islands修改islands/generate.py保存后浏览器会自动刷新展示新岛——因为 Vite 把该脚本的变更作为热更新触发源。生产构建则使用pnpm build:islands # 产物 # - frontend/islands/dist/main.js # - frontend/islands/dist/style.css集成到 SSG 与注意事项在文档站中嵌入islands 最常见的落地场景是静态站点与文档工具。可以将MarimoIslandGenerator写成一个构建期脚本遍历 Markdown/源码中的代码块 →add_code→build()→ 用渲染后的marimo-islandHTML 替换原文 → 把render_head()注入页面head。仓库自身就是例证本文主体所依据的 island_example.md 就是一篇嵌入了三个活岛导入、滑块、响应式 Markdown的 MkDocs 文档页面加载后即由 marimo 运行时激活。限制与注意事项早期特性官方在示例文档与 webassembly_html.md 中都标注了 Preview 状态——API 大概率稳定但功能层面仍会持续改进浏览器端运行响应式岛依赖 Pyodide 在浏览器中执行 Python首次初始化有加载成本可用 init island 缓解且浏览器端需能访问 CDN 资源样式隔离island 不访问父页面 HTML其 UI 样式独立打包避免与宿主站点样式互相污染保持 payload 完整若自行后处理 HTML切勿改动application/vnd.marimo.islandsjson脚本标签build()仅一次MarimoIslandGenerator实例的build()不可重复调用多段内容请先全部add_code再统一构建运行时版本对齐render_head(version_override...)加载的 islands JS/CSS 版本应与生成时所用 marimo 版本匹配避免 DOM 结构与运行时协议不一致。结语从本文可见marimo islands 的价值在于把笔记本单元格降维成可嵌入的 HTML 原语服务端负责执行与预渲染浏览器端运行时负责水合与响应式联动两者通过marimo-island自定义元素与 JSON payload 协议解耦。无论你是想给博客加一个可拖动的滑块演示、给文档站嵌入一段可运行的代码示例还是为 SSG 工具链编写 marimo 集成MarimoIslandGenerator与render_head()/render_body()这套 API 都提供了开箱即用的通路而 generate.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），仅供参考