# 流程图懒加载

> [!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 `Esc` to close — even oversized diagrams stay readable.
- **Non-invasive**: Never modifies your notes; built-in SVG sanitization for XSS protection.

## 安装

### 方式一：从 Obsidian 社区目录安装（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 点击「浏览」，搜索 "XU Mermaid Lazy Render"
3. 点击「安装」，然后「启用」

### 方式二：手动安装

1. 从 [最新 Release](https://github.com/xcloud-ai/xu-mermaid-lazy-render/releases) 下载 `main.js`、`manifest.json`、`styles.css` 三个文件
2. 在 vault 中创建目录 `.obsidian/plugins/mermaid-lazy-render/`
3. 将三个文件放入该目录
4. 打开 Obsidian 设置 → 社区插件，找到 XU Mermaid Lazy Render 并开启

### Installation

**From Obsidian Community Directory:**
1. Open Obsidian Settings → Community Plugins
2. Click "Browse" and search for "XU Mermaid Lazy Render"
3. Click "Install", then "Enable"

**Manual Installation:**
1. Download `main.js`, `manifest.json`, `styles.css` from the [latest release](https://github.com/xcloud-ai/xu-mermaid-lazy-render/releases)
2. Put them in `<vault>/.obsidian/plugins/mermaid-lazy-render/`
3. Enable in Settings → Community Plugins

## 使用方法

1. 安装启用后无需任何配置，含大量 Mermaid 流程图的笔记打开速度显著提升。
2. 视口外的流程图显示为占位符，滚动到附近自动渲染（自动模式）或点击渲染（手动模式）。
3. 按 `Ctrl+P` 可使用「渲染当前笔记所有流程图」「渲染当前视口内的流程图」命令。
4. 在设置面板可调整触发方式、预渲染边距等参数。
5. **点击已渲染的流程图**可全屏查看：鼠标拖动平移，滚轮/双指缩放，双击切换「适应屏幕 / 原始尺寸」，`Esc` 或点击空白处关闭。

> [!NOTE]
> Obsidian 1.13+ 中 Mermaid 默认关闭，需先在 设置 → 编辑器 中开启 Mermaid，否则占位符会提示「Mermaid 未启用」。

### Usage

1. Once enabled, no configuration is needed. Notes with many Mermaid diagrams open much faster.
2. Off-screen diagrams show as placeholders and render automatically when scrolled near (auto mode) or on click (manual mode).
3. Press `Ctrl+P` for "Render all diagrams in current note" or "Render diagrams in current viewport".
4. Adjust trigger mode, pre-render margin, etc. in the settings panel.
5. **Click any rendered diagram** for fullscreen viewing: drag to pan, wheel/pinch to zoom, double-click to toggle fit/actual-size, press `Esc` or 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](https://github.com/beauty-diagram/obsidian-beauty-diagram) 和 [Beautiful Mermaid Renderer](https://github.com/qiaoborui/obsidian-beautiful-mermaid-renderer) 覆盖内置 mermaid 渲染器的实现思路。

## 许可证

MIT License - Copyright (c) 2026 旭说