 在交互式笔记本中构建强调内容)
marimo 的 Callout 提示框用 mo.callout 与 .callout() 在交互式笔记本中构建强调内容【免费下载链接】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导读Callout 是 marimo 提供的强调式内容容器用于在输出中以扁平、带边框的盒子形式突出关键信息样式与 Markdown admonition提示块保持一致。本文以 docs/api/layouts/callout.md 为骨架结合 callout.py、hypertext.py、CalloutPlugin.tsx 与对应测试完整讲解mo.callout()的六种kind视觉变体、title可选标题、动态切换 kind 的交互写法、底层无状态组件的数据流以及mo.md(...).callout()链式调用等实战用法读完即可在自己的笔记本里直接落地使用。一、什么是 Callout与 admonition 同源的强调容器在 marimo 的响应式笔记本reactive notebook中mo.callout()是一个无状态stateless的布局/输出组件它把传入的内容渲染在一个扁平、带边框的盒子里用来强调信息的重要性。它的视觉风格与 Markdown admonition 完全一致官方文档在 hypertext.py 的 docstring 中明确写道A callout renders your HTML element in a flat, bordered box — the same style as markdown admonitions — emphasizing its importance.前端实现也印证了这一点——CalloutOutput.tsx 的注释说明 callout 复用了css/admonition.css的扁平化 admonition 样式每种kind都映射到对应的 admonition 类别const KIND_CLASS: RecordIntent, string { neutral: neutral, info: info, warn: warning, success: success, danger: danger, // alert is deprecated; render as danger alert: danger, };因此Callout 适合用来做执行成功后的提示、危险操作的警告、需要注意的边界条件、中性说明等场景。二、API 签名与 kind 取值2.1mo.callout函数签名mo.callout是模块级函数由 marimo/init.py 从marimo._plugins.stateless.callout导入并对外暴露签名如下见 callout.pymo.callout( value: object, kind: Literal[neutral, warn, success, info, danger] neutral, title: str | None None, ) - Html参数说明参数类型默认值说明valueobject必填要放进提示框中的内容任意可渲染对象markdown、Html、UI 元素等kindLiteral[neutral, warn, success, info, danger]neutral提示框的视觉类别决定边框与图标配色titlestr \| NoneNone可选的加粗标题行放在正文上方源码中通过CalloutKind Literal[neutral, warn, success, info, danger]定义了五种合法取值见 callout.py传入不支持的kind会抛出ValueErrorif kind not in CALLOUT_KINDS: raise ValueError( fUnsupported callout kind: {kind!r}. fExpected one of {CALLOUT_KINDS}. )对应测试 test_callout.py 验证了这一点传入warning注意不是warn会得到ValueError: Unsupported callout kind: warning。2.2 五种 kind 的视觉效果每种kind对应 admonition.css 中的一类配色与图标lucide 图标以 data URI 方式注入随currentColor渲染kindCSS 类标题色图标infoadmonition.info蓝色--blue-11info 圆形图标dangeradmonition.danger红色--red-11octagon-alert 警告图标warnadmonition.warning黄色--yellow-11triangle-alert 三角警示图标successadmonition.success绿色--grass-11circle-check 对勾图标neutraladmonition.neutral灰色--gray-11无图标静默变体见 admonition.css由此可以推断neutral是安静、不带图标的中性说明info/warn/danger/success则分别覆盖提示、警告、危险、成功四类典型语义。三、基础用法与官方示例3.1 最简单的调用import marimo as mo mo.callout(This is a callout, kindneutral)即文档开头示例的核心调用mo.callout(This is a callout, kindcallout_kind.value)。3.2 配合mo.md编写富文本提示value可以是任意可渲染对象最常见的是 markdownmo.md(Hooray, you did it!).callout(kindsuccess)mo.md(Its dangerous to go alone!).callout( kindwarn, titleWarning )上面两个例子出自 hypertext.py 中Html.callout方法的 docstring。3.3 使用title参数添加加粗标题mo.callout( Remember to save your work before running the export., kindwarn, titleHeads up, )title在前端被渲染为带图标前缀的admonition-title行见 CalloutOutput.tsx默认无图标neutral变体即便设置了title也不会显示图标admonition.css。测试 test_callout.py 验证了不传title时渲染结果中不会出现data-title属性。四、动态切换 kind 的交互式示例原文档 marimo-embed 完整还原原文档通过marimo-embed内嵌了一个可交互示例用下拉框实时切换提示框的颜色类别。完整代码如下可直接作为 notebook 的三个单元格运行import marimo as mo app.cell def __(): callout_kind mo.ui.dropdown( labelColor, options[info, neutral, danger, warn, success], valueneutral, ) return app.cell def __(): callout mo.callout(This is a callout, kindcallout_kind.value) return app.cell def __(): mo.vstack([callout_kind, callout], alignstretch, gap0) return要点解读第一个单元格创建mo.ui.dropdown可选项即五种合法 kind默认值neutral第二个单元格用callout_kind.value作为kind参数——这正是响应式笔记本的核心玩法UI 元素的值变化会自动触发依赖它的单元格重跑第三个单元格用mo.vstack(..., alignstretch, gap0)把下拉框与提示框纵向排列gap0让两者紧贴。由于callout是一个普通的 Python 输出对象而非有状态 UI 元素callout_kind.value变化后第二个单元格重新执行mo.callout(...)会基于新的kind重新构建 HTML前端随即以新的配色重新渲染。五、链式调用Html.callout()方法除了模块级函数mo.calloutmarimo 还在Html类上提供了链式方法见 hypertext.pymo.md(...).callout( kind: Literal[neutral, danger, warn, success, info] neutral, title: str | None None, ) - Html它内部只是转发到模块级calloutfrom marimo._plugins.stateless.callout import callout as _callout return _callout(self, kindkind, titletitle)因此mo.md(Hello).callout(kindinfo, titleNote)与mo.callout(mo.md(Hello), kindinfo, titleNote)完全等价。该方法的测试见 test_hypertext.py。类似的转发也出现在Html之外的其他容器上从源码结构看routes.py 和 sidebar.py 上的callout方法同样以*args, **kwargs透传到模块级实现说明该容器可以在更多上下文如 Sidebar 的 Html 结果中复用。六、底层实现从 Python 到前端的完整数据流6.1 Python 侧ContainerHtml与强引用机制callout类继承自ContainerHtml见 callout.py其渲染逻辑位于_build_textdef _build_text(self) - str: args: dict[str, JSONType] { html: self._children[0].text, kind: self._kind, } if self._title is not None: args[title] self._title return build_stateless_plugin( component_namemarimo-callout-output, argsargs, )关键设计在于ContainerHtml的两个行为见 hypertext.py强引用子对象marimo 的 UI 元素注册表只持有元素的弱引用如果容器在构造时只是冻结了child.text被包裹的 UI 元素可能被垃圾回收导致交互失效。ContainerHtml持有子元素的强引用保证包裹的 UI 元素存活每次访问.text实时重建可变子元素例如mo.status.spinner每次访问都会重新渲染而不是在构造时冻结。test_callout.py 中的两个回归测试直接验证了这两点test_callout_retains_strong_reference_to_child删除外部引用并gc.collect()后子元素依然存活test_callout_child_updates_livemo.status.spinner的标题从Loading更新为Done后.text内容随之变化。6.2 前端侧marimo-callout-output无状态组件后端通过build_stateless_plugin(component_namemarimo-callout-output, args...)把数据序列化给前端前端由 CalloutPlugin.tsx 注册的无状态插件接收tagName marimo-callout-output; validator z.object({ html: z.string(), kind: zodIntent, title: z.string().optional(), }); render({ data }) { return ( CalloutOutput html{data.html} kind{data.kind} title{data.title} / ); }CalloutOutput最终渲染为一个div classadmonition ...内部用HtmlOutput渲染html注意alwaysSanitizeHtml{true}即内容会被消毒后展示见 CalloutOutput.tsxtitle则渲染为带图标的admonition-title。完整链路可概括为mo.callout(value, kind, title) → ContainerHtml._build_text() 构建 stateless plugin args → marimo-callout-output 自定义组件标签 → CalloutPlugin.validator 校验数据 → CalloutOutput 渲染 .admonition 容器七、实践建议与注意事项kind 拼写必须精确合法值只有neutral、warn、success、info、danger没有warning、error等常见拼写传错会直接抛ValueErrortitle可省略不传时渲染结果不含data-title属性视觉上更紧凑传了则在正文上方显示加粗标题行内容消毒html属性在前端渲染时经过alwaysSanitizeHtml消毒动态内容可安全嵌入与 admonition 风格统一由于与 Markdown admonition 共用样式表建议在同一个输出页面中保持 Callout 与 admonition 的语义一致如warn↔warning避免视觉混淆适合组合 UI 元素得益于强引用与实时重建机制Callout 可以安全地包裹mo.ui.*元素、mo.status.spinner等可变对象不必担心垃圾回收导致交互失效——这正是 test_callout.py 中test_callout_retains_strong_reference_to_child与test_callout_child_updates_live两个回归测试所守护的行为。相关参考文件docs/api/layouts/callout.md、marimo/_plugins/stateless/callout.py、marimo/_output/hypertext.py、frontend/src/plugins/layout/CalloutPlugin.tsx、frontend/src/components/editor/output/CalloutOutput.tsx、frontend/src/css/admonition.css、tests/_plugins/stateless/test_callout.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 的 Callout 提示框用 mo.callout 与 .callout() 在交互式笔记本中构建强调内容【免费下载链接】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导读Callout 是 marimo 提供的强调式内容容器用于在输出中以扁平、带边框的盒子形式突出关键信息样式与 Markdown admonition提示块保持一致。本文以 docs/api/layouts/callout.md 为骨架结合 callout.py、hypertext.py、CalloutPlugin.tsx 与对应测试完整讲解mo.callout()的六种kind视觉变体、title可选标题、动态切换 kind 的交互写法、底层无状态组件的数据流以及mo.md(...).callout()链式调用等实战用法读完即可在自己的笔记本里直接落地使用。一、什么是 Callout与 admonition 同源的强调容器在 marimo 的响应式笔记本reactive notebook中mo.callout()是一个无状态stateless的布局/输出组件它把传入的内容渲染在一个扁平、带边框的盒子里用来强调信息的重要性。它的视觉风格与 Markdown admonition 完全一致官方文档在 hypertext.py 的 docstring 中明确写道A callout renders your HTML element in a flat, bordered box — the same style as markdown admonitions — emphasizing its importance.前端实现也印证了这一点——CalloutOutput.tsx 的注释说明 callout 复用了css/admonition.css的扁平化 admonition 样式每种kind都映射到对应的 admonition 类别const KIND_CLASS: RecordIntent, string { neutral: neutral, info: info, warn: warning, success: success, danger: danger, // alert is deprecated; render as danger alert: danger, };因此Callout 适合用来做执行成功后的提示、危险操作的警告、需要注意的边界条件、中性说明等场景。二、API 签名与 kind 取值2.1mo.callout函数签名mo.callout是模块级函数由 marimo/init.py 从marimo._plugins.stateless.callout导入并对外暴露签名如下见 callout.pymo.callout( value: object, kind: Literal[neutral, warn, success, info, danger] neutral, title: str | None None, ) - Html参数说明参数类型默认值说明valueobject必填要放进提示框中的内容任意可渲染对象markdown、Html、UI 元素等kindLiteral[neutral, warn, success, info, danger]neutral提示框的视觉类别决定边框与图标配色titlestr \| NoneNone可选的加粗标题行放在正文上方源码中通过CalloutKind Literal[neutral, warn, success, info, danger]定义了五种合法取值见 callout.py传入不支持的kind会抛出ValueErrorif kind not in CALLOUT_KINDS: raise ValueError( fUnsupported callout kind: {kind!r}. fExpected one of {CALLOUT_KINDS}. )对应测试 test_callout.py 验证了这一点传入warning注意不是warn会得到ValueError: Unsupported callout kind: warning。2.2 五种 kind 的视觉效果每种kind对应 admonition.css 中的一类配色与图标lucide 图标以 data URI 方式注入随currentColor渲染kindCSS 类标题色图标infoadmonition.info蓝色--blue-11info 圆形图标dangeradmonition.danger红色--red-11octagon-alert 警告图标warnadmonition.warning黄色--yellow-11triangle-alert 三角警示图标successadmonition.success绿色--grass-11circle-check 对勾图标neutraladmonition.neutral灰色--gray-11无图标静默变体见 admonition.css由此可以推断neutral是安静、不带图标的中性说明info/warn/danger/success则分别覆盖提示、警告、危险、成功四类典型语义。三、基础用法与官方示例3.1 最简单的调用import marimo as mo mo.callout(This is a callout, kindneutral)即文档开头示例的核心调用mo.callout(This is a callout, kindcallout_kind.value)。3.2 配合mo.md编写富文本提示value可以是任意可渲染对象最常见的是 markdownmo.md(Hooray, you did it!).callout(kindsuccess)mo.md(Its dangerous to go alone!).callout( kindwarn, titleWarning )上面两个例子出自 hypertext.py 中Html.callout方法的 docstring。3.3 使用title参数添加加粗标题mo.callout( Remember to save your work before running the export., kindwarn, titleHeads up, )title在前端被渲染为带图标前缀的admonition-title行见 CalloutOutput.tsx默认无图标neutral变体即便设置了title也不会显示图标admonition.css。测试 test_callout.py 验证了不传title时渲染结果中不会出现data-title属性。四、动态切换 kind 的交互式示例原文档 marimo-embed 完整还原原文档通过marimo-embed内嵌了一个可交互示例用下拉框实时切换提示框的颜色类别。完整代码如下可直接作为 notebook 的三个单元格运行import marimo as mo app.cell def __(): callout_kind mo.ui.dropdown( labelColor, options[info, neutral, danger, warn, success], valueneutral, ) return app.cell def __(): callout mo.callout(This is a callout, kindcallout_kind.value) return app.cell def __(): mo.vstack([callout_kind, callout], alignstretch, gap0) return要点解读第一个单元格创建mo.ui.dropdown可选项即五种合法 kind默认值neutral第二个单元格用callout_kind.value作为kind参数——这正是响应式笔记本的核心玩法UI 元素的值变化会自动触发依赖它的单元格重跑第三个单元格用mo.vstack(..., alignstretch, gap0)把下拉框与提示框纵向排列gap0让两者紧贴。由于callout是一个普通的 Python 输出对象而非有状态 UI 元素callout_kind.value变化后第二个单元格重新执行mo.callout(...)会基于新的kind重新构建 HTML前端随即以新的配色重新渲染。五、链式调用Html.callout()方法除了模块级函数mo.calloutmarimo 还在Html类上提供了链式方法见 hypertext.pymo.md(...).callout( kind: Literal[neutral, danger, warn, success, info] neutral, title: str | None None, ) - Html它内部只是转发到模块级calloutfrom marimo._plugins.stateless.callout import callout as _callout return _callout(self, kindkind, titletitle)因此mo.md(Hello).callout(kindinfo, titleNote)与mo.callout(mo.md(Hello), kindinfo, titleNote)完全等价。该方法的测试见 test_hypertext.py。类似的转发也出现在Html之外的其他容器上从源码结构看routes.py 和 sidebar.py 上的callout方法同样以*args, **kwargs透传到模块级实现说明该容器可以在更多上下文如 Sidebar 的 Html 结果中复用。六、底层实现从 Python 到前端的完整数据流6.1 Python 侧ContainerHtml与强引用机制callout类继承自ContainerHtml见 callout.py其渲染逻辑位于_build_textdef _build_text(self) - str: args: dict[str, JSONType] { html: self._children[0].text, kind: self._kind, } if self._title is not None: args[title] self._title return build_stateless_plugin( component_namemarimo-callout-output, argsargs, )关键设计在于ContainerHtml的两个行为见 hypertext.py强引用子对象marimo 的 UI 元素注册表只持有元素的弱引用如果容器在构造时只是冻结了child.text被包裹的 UI 元素可能被垃圾回收导致交互失效。ContainerHtml持有子元素的强引用保证包裹的 UI 元素存活每次访问.text实时重建可变子元素例如mo.status.spinner每次访问都会重新渲染而不是在构造时冻结。test_callout.py 中的两个回归测试直接验证了这两点test_callout_retains_strong_reference_to_child删除外部引用并gc.collect()后子元素依然存活test_callout_child_updates_livemo.status.spinner的标题从Loading更新为Done后.text内容随之变化。6.2 前端侧marimo-callout-output无状态组件后端通过build_stateless_plugin(component_namemarimo-callout-output, args...)把数据序列化给前端前端由 CalloutPlugin.tsx 注册的无状态插件接收tagName marimo-callout-output; validator z.object({ html: z.string(), kind: zodIntent, title: z.string().optional(), }); render({ data }) { return ( CalloutOutput html{data.html} kind{data.kind} title{data.title} / ); }CalloutOutput最终渲染为一个div classadmonition ...内部用HtmlOutput渲染html注意alwaysSanitizeHtml{true}即内容会被消毒后展示见 CalloutOutput.tsxtitle则渲染为带图标的admonition-title。完整链路可概括为mo.callout(value, kind, title) → ContainerHtml._build_text() 构建 stateless plugin args → marimo-callout-output 自定义组件标签 → CalloutPlugin.validator 校验数据 → CalloutOutput 渲染 .admonition 容器七、实践建议与注意事项kind 拼写必须精确合法值只有neutral、warn、success、info、danger没有warning、error等常见拼写传错会直接抛ValueErrortitle可省略不传时渲染结果不含data-title属性视觉上更紧凑传了则在正文上方显示加粗标题行内容消毒html属性在前端渲染时经过alwaysSanitizeHtml消毒动态内容可安全嵌入与 admonition 风格统一由于与 Markdown admonition 共用样式表建议在同一个输出页面中保持 Callout 与 admonition 的语义一致如warn↔warning避免视觉混淆适合组合 UI 元素得益于强引用与实时重建机制Callout 可以安全地包裹mo.ui.*元素、mo.status.spinner等可变对象不必担心垃圾回收导致交互失效——这正是 test_callout.py 中test_callout_retains_strong_reference_to_child与test_callout_child_updates_live两个回归测试所守护的行为。相关参考文件docs/api/layouts/callout.md、marimo/_plugins/stateless/callout.py、marimo/_output/hypertext.py、frontend/src/plugins/layout/CalloutPlugin.tsx、frontend/src/components/editor/output/CalloutOutput.tsx、frontend/src/css/admonition.css、tests/_plugins/stateless/test_callout.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），仅供参考
