marimo 笔记本网页嵌入实战molab iframe、Sandbox 配置与 Islands 三种方案解析【免费下载链接】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 官方文档 docs/guides/publishing/embedding.md 展开系统讲解如何把可交互的 marimo 笔记本嵌入文档站、教学平台或静态网站首选方案是通过 molab 生成 iframe 片段备选方案是自托管GitHub Pages、WASM HTML与 marimo islands。读完本文你将掌握每类嵌入方式的完整 HTML 写法、sandbox各属性的作用与安全边界并能从源码层面理解 marimo 在前端如何探测沙箱能力并优雅降级。三种嵌入路径概览marimo 笔记本嵌入网页共有三条路径按推荐程度排序molab 嵌入官方推荐利用 molab 指南 中的 WebAssembly 预览能力对 GitHub 仓库中的笔记本点击 Share 按钮即可获取 iframe 片段也可以不托管、直接用笔记本源码构造可嵌入 URL。本文档站本身全程采用这种方式嵌入。自托管把笔记本发布到 GitHub Pages 或 自托管 WASM HTML再用 iframe 引入发布后的页面。marimo islands借助 WebAssembly HTML 导出中的 Islands 机制把单个单元格的输出直接嵌进自己的 HTML 页面页面加载后由 marimo 响应式运行时接管适合交互式博客与教程。选择建议嵌入完整可交互笔记本选 molab需要完全控制托管环境选自托管只需要一两个单元格输出嵌入现有页面选 islands。方案一molab 嵌入推荐在 molab 指南 中对 GitHub 笔记本的 WebAssembly 预览点击分享按钮即可复制形如下面的 iframe 片段iframe srchttps://marimo.app/github/marimo-team/gallery-examples/blob/main/notebooks/math/cellular-automaton-art.py/wasm?embedtrue sandboxallow-scripts allow-same-origin allow-downloads allow-popups allow-forms allowmicrophone allowfullscreen loadinglazy /iframeURL 中的embedtrue参数会隐藏 molab 顶栏让嵌入效果更干净sandbox、allow、allowfullscreen三个属性的含义将在后文 sandbox 配置一节逐一拆解。由于嵌入的笔记本通过 WebAssembly 在浏览器中运行被嵌入的笔记本必须满足 WebAssembly 兼容性要求官方还建议用--sandbox参数创建这类笔记本确保依赖被正确内联。从源码直接嵌入无需托管molab 指南 还给出了一条不依赖 GitHub 托管的路径用 lz-string 压缩笔记本源码作为 URL hash 传入即可嵌入任意笔记本https://molab.marimo.io/new/wasm/?embedtrue#code/{compressed}JavaScript 与 Python 端构造方式分别为import { compressToEncodedURIComponent } from lz-string; const url https://molab.marimo.io/new/wasm/?embedtrue#code/${compressToEncodedURIComponent(code)};import lzstring lz lzstring.LZString() compressed lz.compressToEncodedURIComponent(code) url fhttps://molab.marimo.io/new/wasm/?embedtrue#code/{compressed}两个实用变体空的可编辑笔记本docs/guides/molab.md提供了现成的 Embed an empty editable notebook 配方嵌入一个压缩后的空笔记本 hash 后读者可在嵌入框中直接编辑运行小笔记本的简化形式对小于 14 KB 的笔记本可以直接用 URI 编码的code查询参数替代 lz 压缩例如https://marimo.app/new/wasm/?embedtruecode{encodedURIComponent}。注意查询参数必须放在 hash 之前形如?embedtrue#code/...。方案二自托管嵌入如果必须自托管官方文档给出两条路GitHub Pages / 自托管 WASM HTML iframe先按 GitHub Pages 发布指南 或 self_host_wasm 指南 发布笔记本再把发布后的 URL 写进 iframe。sandbox 配置要求与 molab 嵌入完全一致下文配置章节的结论可直接复用。marimo islandsdocs/guides/exporting/webassembly_html.md中的 Islands 章节说明MarimoIslandGenerator会为每个单元格输出自定义marimo-island标签与一个application/vnd.marimo.islandsjson的 script 数据块页面加载时 islands 运行时读取该 payload 完成水合hydration让原本静态的输出恢复交互。官方提供了一个 island 驱动的示例文档 可以参考效果。需要注意若对 islands 生成的 HTML 做后处理必须原样保留该 JSON script 标签否则水合会失败。iframe Sandbox 配置详解在沙箱化 iframe 中嵌入 marimo 时sandbox 配置直接决定功能完整度。marimo 前端的设计目标是当某些能力被限制时优雅降级graceful degradation而不是直接不可用。理解每个属性对应哪些能力才能给出最佳体验。最小可用配置只有 allow-scriptsmarimo 能跑起来所需的最低限度sandbox 属性只有一个iframe srchttps://marimo.app/github/marimo-team/gallery-examples/blob/main/notebooks/math/cellular-automaton-art.py/wasm sandboxallow-scripts width100% height600 /iframeallow-scripts必需。marimo 的前端完全依赖 JavaScript 执行没有它什么都不会发生。仅配置allow-scripts时marimo 仍可用但有明确限制官方文档原文归纳WebSocket 连接正常工作因此核心执行链路不受影响存储退化为纯内存localStorage 不可用状态在页面刷新后重置剪贴板退化为浏览器提示框无法使用 Clipboard API复制操作会弹出浏览器原生确认提示。推荐配置五个 sandbox 属性 麦克风权限为了完整体验官方推荐补充以下属性iframe srchttps://marimo.app/github/marimo-team/gallery-examples/blob/main/notebooks/math/cellular-automaton-art.py/wasm sandboxallow-scripts allow-same-origin allow-downloads allow-popups allow-forms allowmicrophone allowfullscreen width100% height600 /iframe各属性的作用与影响属性类型解锁的能力说明allow-same-originsandbox持久化存储localStorage 完整 Clipboard API仅当信任 iframe 内容、或 iframe 域名与宿主不同时使用allow-downloadssandbox下载笔记本输出、数据导出、截图对应输出面板的下载按钮allow-popupssandbox在新标签页打开链接和笔记本保证导航类交互不被拦截allow-formssandbox表单提交交互式 UI 组件如mo.ui.form所必需allowfullscreen普通属性非 sandbox 值幻灯片与输出的全屏模式注意它不属于sandbox的取值allowmicrophonePermission Policymo.ui.microphone()组件麦克风权限通过独立的 Permission Policy 声明不放进 sandbox安全考量allow-same-origin 的正确用法官方文档给出了明确的警告tip 级别allow-same-origin只应用于你信任的内容或者 iframe URL 与宿主处于不同域名时原因在于allow-scripts与allow-same-origin同时存在时iframe 内的脚本可以移除 sandbox 属性本身从而让 iframe 拥有与未沙箱化时同等的权限。因此对不可信的第三方 iframe应牺牲 localStorage/剪贴板能力换取隔离性这也与最小可用配置一节中降级行为正好呼应。可直接复制的完整示例官方给出的全量推荐设置示例附加了allow-downloads-without-user-activation允许无需用户交互触发的下载例如数据导出与moderead只读模式嵌入并附带内联样式iframe srchttps://marimo.app/github/marimo-team/gallery-examples/blob/main/notebooks/math/cellular-automaton-art.py/wasm?embedtruemoderead sandboxallow-scripts allow-same-origin allow-downloads allow-popups allow-forms allow-downloads-without-user-activation allowmicrophone allowfullscreen width100% height600 styleborder: 1px solid #ddd; border-radius: 8px; /iframe源码佐证marimo 如何探测沙箱能力并降级上文优雅降级并非营销措辞marimo 前端在启动时就有对应的能力探测实现。frontend/src/utils/capabilities.ts 中的detectIframeCapabilities()在应用启动时执行一次并缓存见 第 114 行的getIframeCapabilities探测项与 sandbox 属性一一对应探测项探测方式对应的 sandbox 属性isEmbeddedwindow.parent ! window——判断是否处于 iframehasLocalStorage/hasSessionStorage实际写入/读取/删除一个测试键testStorage第 29–47 行allow-same-originhasClipboardnavigator.clipboard ! undefinedallow-same-originhasDownloads检查a元素是否支持download属性allow-downloadshasFullscreendocument.fullscreenEnabledallowfullscreenhasMediaDevicesnavigator.mediaDevices.getUserMedia是否可用allowmicrophone当探测到处于嵌入环境且某项能力缺失时detectIframeCapabilities会通过 Logger 输出对应警告例如localStorage unavailable - using fallback storage第 84–106 行。存储回退逻辑实现在 frontend/src/utils/storage/storage.ts 中localStorage 不可用时切换为内存存储这正是刷新后状态重置现象的根源相关的行为验证可参考 frontend/src/utils/tests/capabilities.test.ts 与 frontend/src/utils/tests/storage.test.ts。从源码结构看这套启动时一次性探测 缓存的设计意味着你在 iframe 上配置哪些 sandbox 属性直接决定了 marimo 走完整路径还是降级路径且该判断在页面生命周期内只发生一次——改 sandbox 配置后需要刷新嵌入页面才能生效。落地清单把三个方案与配置要点收拢成一张可核对的清单首选 molabGitHub 笔记本走Share → Copy Embed Iframe一键获取片段临时演示可用 lz-string 压缩源码构造#code/URL小于 14 KB 的笔记本可改用code查询参数。自托管GitHub Pages 或 self-hosted WASM HTML 发布后 iframe 引入只需部分单元格交互时改用 islands 的application/vnd.marimo.islandsjson水合机制。sandbox 最小集是allow-scripts存储与剪贴板会降级推荐集再加上allow-same-origin allow-downloads allow-popups allow-formsallowmicrophoneallowfullscreen。安全红线allow-scripts与allow-same-origin组合会解除沙箱只对可信内容或跨域场景启用。验证方式嵌入后打开控制台marimo 会输出[iframe] ...系列日志逐项标出当前缺失的能力存储、剪贴板、下载、全屏、媒体设备可与本文对照定位配置缺口。【免费下载链接】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），仅供参考