README file from
Github流程图懒加载
[!NOTE] 中文说明 流程图懒加载:视口外的 Mermaid 流程图延迟渲染,打开含大量图表的笔记不再卡顿。
打开一篇包含几十个 Mermaid 流程图的笔记时,Obsidian 会同步渲染所有图表,导致卡顿几秒才能正常操作。本插件接管 Mermaid 渲染,只渲染屏幕可见区域内的流程图,其余滚动到附近时再加载,大幅提升打开速度。不修改任何笔记内容,关闭插件即恢复原生渲染。
English description below for review purposes. / 以下为英文说明,用于过审。
XU Mermaid Lazy Render is an Obsidian plugin that defers rendering of off-screen Mermaid diagrams. Instead of rendering every diagram synchronously when a note opens (which freezes the UI for seconds on diagram-heavy notes), only diagrams in or near the viewport are rendered; the rest load on demand as you scroll. Your notes are never modified — disabling the plugin restores native rendering.
功能特性
- 视口懒渲染:默认只渲染屏幕可见的流程图,其余占位,滚动到附近才加载。
- 双触发模式:自动(滚动到视口附近渲染)或手动(点击占位符渲染)。
- 预渲染边距可调:设置距离视口多少像素内开始渲染,平衡加载时机与流畅度。
- 占位符显示图表类型:一眼看出是 flowchart 还是 sequenceDiagram。
- 主题切换自动重渲染:明暗主题切换后,已显示的流程图自动重绘适配新主题。
- 一键全渲染:命令面板提供「渲染当前笔记所有流程图」「渲染视口内流程图」。
- 点击看大图:正文中的流程图默认适配页宽保持版面整齐;点击流程图弹出全屏灯箱,可拖动平移、滚轮缩放、双击在「适应屏幕 / 原始尺寸」间切换,
Esc退出,超大图表也能看清。 - 零侵入:不修改笔记内容,关闭插件即恢复原生渲染;内置 SVG 消毒防 XSS。
Features
- Viewport lazy rendering: Only visible diagrams render by default; off-screen diagrams stay as placeholders until you scroll near them.
- Two trigger modes: Auto (render near viewport) or manual (click placeholder to render).
- Adjustable pre-render margin: Control how close to the viewport a diagram must be before rendering.
- Diagram type on placeholder: Quickly tell flowchart from sequenceDiagram at a glance.
- Auto re-render on theme change: Visible diagrams redraw when switching light/dark theme.
- Render-all commands: "Render all diagrams in current note" and "Render diagrams in viewport" via command palette.
- Click to enlarge: Diagrams fit page width inline to keep the layout tidy; click any rendered diagram to open a fullscreen lightbox with drag-to-pan, wheel-to-zoom, double-click to toggle fit/actual-size, and
Escto close — even oversized diagrams stay readable. - Non-invasive: Never modifies your notes; built-in SVG sanitization for XSS protection.
安装
方式一:从 Obsidian 社区目录安装(推荐)
- 打开 Obsidian 设置 → 社区插件
- 点击「浏览」,搜索 "XU Mermaid Lazy Render"
- 点击「安装」,然后「启用」
方式二:手动安装
- 从 最新 Release 下载
main.js、manifest.json、styles.css三个文件 - 在 vault 中创建目录
.obsidian/plugins/mermaid-lazy-render/ - 将三个文件放入该目录
- 打开 Obsidian 设置 → 社区插件,找到 XU Mermaid Lazy Render 并开启
Installation
From Obsidian Community Directory:
- Open Obsidian Settings → Community Plugins
- Click "Browse" and search for "XU Mermaid Lazy Render"
- Click "Install", then "Enable"
Manual Installation:
- Download
main.js,manifest.json,styles.cssfrom the latest release - Put them in
<vault>/.obsidian/plugins/mermaid-lazy-render/ - Enable in Settings → Community Plugins
使用方法
- 安装启用后无需任何配置,含大量 Mermaid 流程图的笔记打开速度显著提升。
- 视口外的流程图显示为占位符,滚动到附近自动渲染(自动模式)或点击渲染(手动模式)。
- 按
Ctrl+P可使用「渲染当前笔记所有流程图」「渲染当前视口内的流程图」命令。 - 在设置面板可调整触发方式、预渲染边距等参数。
- 点击已渲染的流程图可全屏查看:鼠标拖动平移,滚轮/双指缩放,双击切换「适应屏幕 / 原始尺寸」,
Esc或点击空白处关闭。
[!NOTE] Obsidian 1.13+ 中 Mermaid 默认关闭,需先在 设置 → 编辑器 中开启 Mermaid,否则占位符会提示「Mermaid 未启用」。
Usage
- Once enabled, no configuration is needed. Notes with many Mermaid diagrams open much faster.
- Off-screen diagrams show as placeholders and render automatically when scrolled near (auto mode) or on click (manual mode).
- Press
Ctrl+Pfor "Render all diagrams in current note" or "Render diagrams in current viewport". - Adjust trigger mode, pre-render margin, etc. in the settings panel.
- Click any rendered diagram for fullscreen viewing: drag to pan, wheel/pinch to zoom, double-click to toggle fit/actual-size, press
Escor click the backdrop to close.
设置说明
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 启用懒加载 | 开 | 关闭后恢复 Obsidian 原生渲染 |
| 渲染触发方式 | 自动 | 自动=滚动到视口附近渲染;手动=点击才渲染 |
| 预渲染边距 | 200px | 距离视口多少像素内开始渲染 |
| 占位符显示图表类型 | 开 | 占位符上显示流程图类型 |
| 主题切换时重新渲染 | 开 | 切换明暗主题后自动重绘已显示的图 |
命令列表
| 命令 | 作用 |
|---|---|
| 渲染当前笔记中所有流程图 | 强制渲染当前笔记内所有未渲染的 Mermaid 图 |
| 渲染当前视口内的流程图 | 只渲染当前屏幕可见区域的流程图 |
技术说明
- 通过
registerMarkdownCodeBlockProcessor('mermaid', ...)接管 Obsidian 内置 Mermaid 渲染器(与 Beauty Diagram / Beautiful Mermaid Renderer 同一机制)。 - 每个流程图用
MarkdownRenderChild管理生命周期,文档关闭时自动断开IntersectionObserver、取消渲染,无内存泄漏。 - 渲染使用 Obsidian 自带的
window.mermaid.render(),输出与原生一致;渲染前对 SVG 做消毒(移除on*事件属性、<script>/<iframe>、javascript:URL)。 - 主题切换通过
MutationObserver监听body.class的theme-light/theme-dark变化,重渲染已显示的图。 - 不使用 Node/Electron API,支持桌面端与移动端(
isDesktopOnly: false)。 - 与其他修改 Mermaid 的插件(如 Mermaid Next、Beauty Diagram)可能冲突,建议二选一。
致谢 / Credits
- 借鉴了社区插件 Beauty Diagram 和 Beautiful Mermaid Renderer 覆盖内置 mermaid 渲染器的实现思路。
许可证
MIT License - Copyright (c) 2026 旭说