# 美人鱼.js deep dive:它如何实际运作以及如何扩展它
2025-11-09T16:00
# 一. 导言 导言 导言 导言 导言 导言 一,导言 导言 导言 导言 导言 导言
> 注意:这是我在AI的实验的一部分 / 一种花费1000美元 Clude 代码 Web 信用的方法。 我给这个文件,我的理解,我不得不提出这样的问题。这很有趣,填补了一个我还没有看到的地方填补的空白。
> **该员额以以前各条为基础:** 如果你还没有,你看看 [添加美人鱼。 js 与 htmx](/blog/mermaidandhtmx), [为美人鱼切换主题](/blog/switchingthemesformermaid), 和 [使用 Pan/Zoom 和 导出加强美人鱼图](/blog/enhancingmermaiddiagramswithpanzoomandexport)这种深度的下潜解释这些执行背后的内在原因。
Mermaid.js 是真正的天才。 写入简单的文字, 获得美丽的图表。 不再用 Visio 或 draw. io 来折腾 Visio 或 draw. io , 丢失源文件, 或者保留单独的图像文件 。 所有的东西都生活在标记下, 版本控制与您的代码并存 。
但我想知道 *如何如何* 它实际上在引擎盖下工作。
```mermaid
graph LR
A[Text] --> B[Magic?]
B --> C[Beautiful Diagram]
```
...成为一个真实的SVG?更重要的是,你怎样才能勾上它来添加一些功能,例如Pan/zoom,主题转换, 以及我为这个网站建立的输出功能(现在可用) [@ mostlylucid/ permaid- envenancements @ 最优优/ 美人鱼增强](https://www.npmjs.com/package/@mostlylucid/mermaid-enhancements))?
经过大量调查 美人鱼的源代码 和构建真正的扩展, 这是我所学到的一切 关于美人鱼的内部工作方式 以及如何适当扩展它。
[TOC]
# 美人鱼是什么?
美人鱼将文本定义转换为图表。 想象一下“ 图表的 Markdown ” 。
**旧的方式:**
1. Open 图表绘制工具
2. 创建图表
3. 作为巴布亚新几内亚出口
4. 嵌入于 Docs 中
5. 需要更新吗? 查找源文件, 编辑, 再导出, 替换图像...
**美人鱼的方式:**
1. 文本中写入图表
2. 完成完成完成完成
更新? 编辑文本。 版本控制? 它只是文本! 在标记中有用吗?
## 图表类型
美人鱼支持数量荒谬的图表类型:
```mermaid
graph LR
A[Flowcharts] --> B[Sequence Diagrams]
B --> C[Class Diagrams]
C --> D[State Diagrams]
D --> E[ER Diagrams]
E --> F[Gantt Charts]
F --> G[Pie Charts]
G --> H[Git Graphs]
H --> I[User Journeys]
I --> J[And many more...]
```
见见 [美人鱼博士](https://mermaid.js.org/intro/) 全部名单。
# 美人鱼如何实际工作:管道
美人鱼提供图表时会发生什么:
```mermaid
graph TD
A[Text Definition] --> B[Lexer/Tokenizer]
B --> C[Parser]
C --> D[AST Built]
D --> E[Diagram Type Detected]
E --> F[Type-Specific Renderer]
F --> G[SVG Generated]
G --> H[Inserted into DOM]
H --> I[Your Enhancements Run]
style A stroke:#059669,stroke-width:3px,color:#10b981
style D stroke:#2563eb,stroke-width:3px,color:#3b82f6
style G stroke:#7c3aed,stroke-width:3px,color:#8b5cf6
style I stroke:#d97706,stroke-width:3px,color:#f59e0b
```
让我们打破每一步。
## 第1步:文本定义
一切从文字开始。 您以美人鱼 DSL (域名语言) 写入图表 :
```javascript
// Flowchart
const diagram = `
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug time]
`;
```
## 步骤2:词汇分析
名词典将文本拆分为符号。 例如, 此行 :
```
A[Start] --> B{Decision}
```
成为像 :
```javascript
[
{ type: 'NODE_ID', value: 'A' },
{ type: 'NODE_TEXT', value: 'Start' },
{ type: 'ARROW', value: '-->' },
{ type: 'NODE_ID', value: 'B' },
{ type: 'NODE_TEXT', value: 'Decision' },
{ type: 'NODE_SHAPE', value: 'diamond' } // from { }
]
```
## 步骤3:划分和AST的产生
解析器消耗象征物并构建一个抽象的语法树( AST ) :
```javascript
// Simplified AST structure
{
type: 'flowchart',
direction: 'TD',
nodes: [
{ id: 'A', text: 'Start', shape: 'rect' },
{ id: 'B', text: 'Decision', shape: 'diamond' }
],
edges: [
{ from: 'A', to: 'B', type: 'arrow' }
]
}
```
美人鱼对每一图表类型使用不同的解析器。 这些解析器通常是用语法文件生成的。 [Jison 联合](https://github.com/zaach/jison) (如JavaScript的Yacc/Bison)。
## 步骤4:图解检测
美人鱼检测第一行的图表类型 :
```javascript
// Simplified detection logic
if (text.match(/^\s*graph/)) return 'flowchart';
if (text.match(/^\s*sequenceDiagram/)) return 'sequence';
if (text.match(/^\s*classDiagram/)) return 'class';
// ... etc
```
## 第5步:具体类型招标
每个图表类型都有自己的生成器。 生成器使用 AST 并生成 SVG 元素 。
对于流程图,美人鱼使用 [达格](https://github.com/dagrejs/dagre) 用于图形布局的库。 对于其他的库, 它使用自定义算法或像 Cytoscape 这样的库 。
```javascript
// Simplified flowchart renderer
export const draw = function (text, id, version, diagObj) {
const graph = diagObj.db; // The AST
const svg = d3.select(`#${id}`);
// Render nodes
graph.getVertices().forEach(vertex => {
drawNode(svg, vertex);
});
// Render edges
graph.getEdges().forEach(edge => {
drawEdge(svg, edge);
});
// Apply layout algorithm
dagre.layout(graph);
};
```
## 步骤6:建立SVG
制造者生产SVG标记:
```xml
```
## 第7步:插入DOM
美人鱼找到所有的东西 `.mermaid` 将其替换为已设定的 SVG :
```javascript
// From mermaid.ts
export const init = async function (config, nodes) {
const nodesToProcess = nodes || document.querySelectorAll('.mermaid');
for (const node of nodesToProcess) {
const id = `mermaid-${Date.now()}-${Math.random()}`;
const txt = node.textContent;
const { svg } = await render(id, txt);
node.innerHTML = svg;
}
};
```
## 步骤8:处理后(进入何处)
在美人鱼插入 SVG 后, 您可以加强它。 这是我所有的增强钩 :
- Pananzoom功能/Panzoom功能
- 控制按钮
- 出口能力
- 主题切换
下文将进一步阐述这方面的情况。
# 扩展美人鱼:扩展点
现在我们知道美人鱼是如何工作的了, 让我们来探索如何扩展它。
## 1. 配置
最基本的扩展名为配置 :
```javascript
import mermaid from 'mermaid';
mermaid.initialize({
startOnLoad: true,
theme: 'dark',
securityLevel: 'loose',
flowchart: {
curve: 'basis',
padding: 15
}
});
```
## 2. 主题定制
我广泛报道了 [为美人鱼切换主题](/blog/switchingthemesformermaid),但这里是关键执行:
### 主题转换问题
美人鱼需要以主题初始化, 之后无法更改它。 但是, 如果您想要用新主题重新生成图表, 您需要原始的图表源 — — 哪个美人鱼 。 *不存储在DOM*.
### 解决方案
在转换主题前存储原始内容, 然后恢复并重新发送 :
```javascript
// From my theme-switcher implementation
const originalData = new Map();
// Save original content before first render
const saveOriginalData = async () => {
const elements = document.querySelectorAll('.mermaid');
elements.forEach(element => {
const id = element.id || `mermaid-${Date.now()}`;
element.id = id;
// Store the original diagram source
if (!originalData.has(id)) {
originalData.set(id, element.textContent?.trim());
}
});
};
// When theme changes, restore and re-render
const loadMermaid = async (theme) => {
mermaid.initialize({
startOnLoad: false,
theme: theme
});
const elements = document.querySelectorAll('.mermaid');
for (const element of elements) {
const source = originalData.get(element.id);
if (source) {
element.innerHTML = ''; // Clear
element.removeAttribute('data-processed');
const { svg } = await mermaid.render(
`mermaid-svg-${element.id}`,
source
);
element.innerHTML = svg;
}
}
};
```
**多主题检测方法** (网站处理主题不同):
```javascript
function detectTheme() {
// Check various sources
if (typeof window.__themeState !== 'undefined') {
return window.__themeState;
}
if (localStorage.theme) {
return localStorage.theme;
}
if (document.documentElement.classList.contains('dark')) {
return 'dark';
}
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
return 'dark';
}
return 'light';
}
```
见见 [整个主题切换码](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid/src/js/memmaid_theme_switch.js) 详细信息。
## 3. 投标后强化
这就是真正的魔法发生的地方。在美人鱼投产后,你可以添加互动功能。
我广泛报道了 [使用 Pan/Zoom 和 导出加强美人鱼图](/blog/enhancingmermaiddiagramswithpanzoomandexport)所以我要在此强调关键技术
### 包装图
创建用于控制的包装容器 :
```javascript
function wrapDiagram(element) {
if (element.closest('.mermaid-wrapper')) {
return element.closest('.mermaid-wrapper');
}
const wrapper = document.createElement('div');
wrapper.className = 'mermaid-wrapper';
wrapper.id = `wrapper-${element.id}`;
element.parentNode.insertBefore(wrapper, element);
wrapper.appendChild(element);
return wrapper;
}
```
### 正在添加空/ 缩放
使用 [svg-pan-zoom (svg-pan-zoom)](https://github.com/bumbu/svg-pan-zoom):
```javascript
import svgPanZoom from 'svg-pan-zoom';
const panZoomInstances = new Map();
function initPanZoom(svgElement, diagramId) {
// Clean up existing instance
if (panZoomInstances.has(diagramId)) {
panZoomInstances.get(diagramId).destroy();
panZoomInstances.delete(diagramId);
}
const instance = svgPanZoom(svgElement, {
zoomEnabled: true,
controlIconsEnabled: false,
fit: true,
center: true,
minZoom: 0.1,
maxZoom: 10
});
panZoomInstances.set(diagramId, instance);
return instance;
}
```
### 控制按钮
创建浮动控制面板 :
```javascript
function createControlButtons(container, diagramId) {
const controlsDiv = document.createElement('div');
controlsDiv.className = 'mermaid-controls';
const buttons = [
{ icon: 'bx-fullscreen', title: 'Fullscreen', action: 'fullscreen' },
{ icon: 'bx-zoom-in', title: 'Zoom In', action: 'zoomIn' },
{ icon: 'bx-zoom-out', title: 'Zoom Out', action: 'zoomOut' },
{ icon: 'bx-reset', title: 'Reset', action: 'reset' },
{ icon: 'bx-move', title: 'Pan', action: 'pan' },
{ icon: 'bx-image', title: 'Export PNG', action: 'exportPng' },
{ icon: 'bx-code-alt', title: 'Export SVG', action: 'exportSvg' }
];
buttons.forEach(btn => {
const button = document.createElement('button');
button.className = `mermaid-control-btn bx ${btn.icon}`;
button.setAttribute('data-action', btn.action);
button.setAttribute('data-diagram-id', diagramId);
controlsDiv.appendChild(button);
});
container.appendChild(controlsDiv);
}
```
### 活动代表团(表现! )
不要给每个按钮附加听众。使用事件授权 :
```javascript
document.addEventListener('click', (e) => {
const target = e.target;
if (!target.classList.contains('mermaid-control-btn')) return;
const action = target.getAttribute('data-action');
const diagramId = target.getAttribute('data-diagram-id');
const panZoom = panZoomInstances.get(diagramId);
switch (action) {
case 'zoomIn': panZoom?.zoomIn(); break;
case 'zoomOut': panZoom?.zoomOut(); break;
case 'reset': panZoom?.reset(); break;
// ... etc
}
});
```
### 出口功能
**挑战:** SVG 元素具有动态缩放、泛形/声波变换和继承风格。 要正确导出, 您需要 :
1. 克隆 SVG
2. 保全维度
3. 删除变换
4. 转换为 PNG 或 SVG
使用 [html到图像](https://github.com/bubkoo/html-to-image):
```javascript
import { toPng, toSvg } from 'html-to-image';
async function exportDiagram(container, format, diagramId) {
const svgElement = container.querySelector('svg');
if (!svgElement) return;
// Clone to avoid modifying original
const clonedSvg = svgElement.cloneNode(true);
// Get or calculate viewBox
let viewBox = clonedSvg.getAttribute('viewBox');
if (!viewBox) {
const bbox = svgElement.getBBox();
viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
clonedSvg.setAttribute('viewBox', viewBox);
}
// Set explicit dimensions
const [, , width, height] = viewBox.split(' ').map(Number);
clonedSvg.setAttribute('width', width);
clonedSvg.setAttribute('height', height);
// Remove pan-zoom transforms
clonedSvg.removeAttribute('style');
// Create off-screen container
const temp = document.createElement('div');
temp.style.position = 'absolute';
temp.style.left = '-9999px';
temp.appendChild(clonedSvg);
document.body.appendChild(temp);
// Export
const dataUrl = format === 'png'
? await toPng(clonedSvg, { pixelRatio: 2 })
: await toSvg(clonedSvg);
downloadFile(dataUrl, `diagram-${Date.now()}.${format}`);
// Cleanup
document.body.removeChild(temp);
}
```
**关键细节:**
- **保存保护视图框** - 捕捉整个图表,而不仅仅是可见部分
- **外部屏幕覆盖** - 避免影响显示图表
- **像像像像像像像像像路数: 2** - 巴布亚新几内亚出口出口品高报
见见 [完整导出代码](https://github.com/scottgal/mostlylucidweb/blob/main/Mostlylucid/src/js/mermaid_enhancements.js#L148) 以获取更多细节。
# 完整增强套件
我将所有这些增强功能包装为 [@ mostlylucid/ permaid- envenancements @ 最优优/ 美人鱼增强](https://www.npmjs.com/package/@mostlylucid/mermaid-enhancements)见 [作为 npm 软件包的美人鱼增强](/blog/publishingmermaidenhancementsnpm) 用于完整细节。
以下是一切合而为一:
```mermaid
graph TB
A[User Initializes] --> B[init Function]
B --> C[initMermaid]
B --> D[enhanceMermaidDiagrams]
C --> E[Theme Detection]
C --> F[Event Listeners]
C --> G[Mermaid Rendering]
E --> E1[Global State]
E --> E2[LocalStorage]
E --> E3[DOM Class]
E --> E4[OS Preference]
F --> F1[Custom Events]
F --> F2[Media Query]
G --> H[Apply Enhancements]
D --> H
H --> I[Wrap Diagrams]
H --> J[Init Pan/Zoom]
H --> K[Add Controls]
I --> L[Interactive Diagram]
J --> L
K --> L
L --> M[User Interactions]
M --> M1[Zoom In/Out]
M --> M2[Pan]
M --> M3[Fullscreen]
M --> M4[Export PNG/SVG]
style A stroke:#059669,stroke-width:3px,color:#10b981
style L stroke:#2563eb,stroke-width:3px,color:#3b82f6
style M stroke:#7c3aed,stroke-width:3px,color:#8b5cf6
```
## 用法
```bash
npm install @mostlylucid/mermaid-enhancements
```
```typescript
import { init } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
await init();
```
就是这样,你的美人鱼图现在有:
- 交互式的Pan/zoom
- 全屏灯盒
- PNG/SVG出口
- 自动切换主题
- 反应性设计
# 与HTMX结合
正如我所覆盖的 [添加美人鱼。 js 与 htmx](/blog/mermaidandhtmx)HTMX 内容互换后, 您需要重新激活美人鱼 :
```javascript
// On page load
document.addEventListener('DOMContentLoaded', function () {
mermaid.initialize({ startOnLoad: true });
});
// After HTMX swaps content
document.body.addEventListener('htmx:afterSwap', function(evt) {
mermaid.run();
});
```
结合强化一揽子计划:
```javascript
import { init, enhanceMermaidDiagrams } from '@mostlylucid/mermaid-enhancements';
// Initial load
await init();
// After HTMX swap
document.body.addEventListener('htmx:afterSwap', async function() {
await init(); // Re-init Mermaid with current theme
enhanceMermaidDiagrams(); // Re-apply enhancements
});
```
# 最佳做法
在建了这个东西 并调试了奇异的边缘案例之后, 这里的原理是:
## 1. 总是存储原始内容
美人鱼不会保存原始图表来源。
```javascript
const originalData = new Map();
// Before first render
element.setAttribute('data-original-code', element.textContent);
originalData.set(element.id, element.textContent);
// When re-rendering
element.innerHTML = originalData.get(element.id);
```
## 2. 清洁项目
内存泄漏是真实的。 在创建新事件之前销毁实例 :
```javascript
if (panZoomInstances.has(id)) {
try {
panZoomInstances.get(id).destroy();
} catch (e) {
console.warn('Failed to destroy:', e);
}
panZoomInstances.delete(id);
}
```
## 3. 利用活动代表团
不要将收听者附加在单按钮上 :
```javascript
// ❌ Don't do this
buttons.forEach(btn => {
btn.addEventListener('click', handler);
});
// ✅ Do this
document.addEventListener('click', (e) => {
if (e.target.matches('.mermaid-control-btn')) {
handleClick(e.target);
}
});
```
## 4. Handle Cloudflare火箭装载器
火箭加载器延迟 JavaScript 执行。 等待依赖关系 :
```javascript
function waitForDependencies(maxAttempts = 50) {
return new Promise((resolve) => {
let attempts = 0;
const check = () => {
if (window.mermaid && window.htmx && window.Alpine) {
resolve();
} else if (attempts >= maxAttempts) {
resolve(); // Give up
} else {
attempts++;
setTimeout(check, Math.min(50 * Math.pow(1.2, attempts), 500));
}
};
check();
});
}
```
将您的主要脚本从火箭加载器中排除 :
```html
```
## 5. 时间是一切
使用使用 `requestAnimationFrame` B. 时间比任意选择更合适 `setTimeout`:
```javascript
// After Mermaid renders
await mermaid.run();
// Wait for paint before enhancing
await new Promise(resolve => {
requestAnimationFrame(() => {
requestAnimationFrame(() => {
enhanceMermaidDiagrams();
resolve();
});
});
});
```
## 6. 防御性SVG处理
SVGs可能很奇怪,总是检查:
```javascript
const svgElement = container.querySelector('svg');
if (!svgElement) {
console.warn('No SVG found');
return;
}
// Clone before modifying
const cloned = svgElement.cloneNode(true);
// Ensure viewBox exists
let viewBox = cloned.getAttribute('viewBox');
if (!viewBox) {
const bbox = svgElement.getBBox();
viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
}
```
# 调试提示
## 控制台输出
适当初始化后,您应该看到:
```
Saving original data
Loading mermaid with theme: dark
Mermaid initialized
Enhanced 3 diagrams
```
## 测试核对清单
实施增强后:
- [ 页面载荷显示的图
- [ 潘道姆/祖宗控制工作
- [ 全屏打开/关闭(X,单击外面,ESC)
- [ PNG 出口捕捉完整图表
- [ SVG出口保留地矢量
- [ HTMX 内容互换后工作
- [ 主题切换正确重现
- [ 移动响应
- [ 黑暗模式的外观
- [ 键盘无障碍
## 共同问题 共同问题
**图表未创建 :**
- 检查浏览器控制台错误
- 已装入美人鱼核查( )`window.mermaid`)
- 检查图表语法
**不起作用的Panzoom:**
- 校验 svg-pan-zoom 初始化
- 检查相冲突的 CSS (CSS)`pointer-events: none`)
- 检查实例映射图
**只抓取导出角 :**
- 缺少视图包保存
- 变换未删除
- 核查克隆逻辑
**主题未切换 :**
- 未保存原始数据
- `data-processed` 未重置
- 未注册的活动听众
# 绩效考量
## Lazy 缩放初始化
需要之前不要加载增强装置 :
```javascript
let enhancementsLoaded = false;
async function loadEnhancements() {
if (enhancementsLoaded) return;
const { enhanceMermaidDiagrams } = await import('./enhancements.js');
enhanceMermaidDiagrams();
enhancementsLoaded = true;
}
// Load on first interaction
document.addEventListener('click', (e) => {
if (e.target.closest('.mermaid')) {
loadEnhancements();
}
}, { once: true });
```
## 跨部门观察员
仅在可见时才显示图像图 :
```javascript
const observer = new IntersectionObserver((entries) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
renderDiagram(entry.target);
observer.unobserve(entry.target);
}
});
}, { rootMargin: '100px' });
document.querySelectorAll('.mermaid').forEach(el => {
observer.observe(el);
});
```
## Debcuns 重新显示
更改大小或主题更改时 :
```javascript
let timeout;
window.addEventListener('resize', () => {
clearTimeout(timeout);
timeout = setTimeout(() => {
panZoomInstances.forEach(instance => {
instance.resize();
instance.fit();
});
}, 250);
});
```
# 在结论结论中
美人鱼.js是绝妙的盒子外, 但了解内部如何运作, 让你建立一些非常酷的增强。 关键洞察力 :
1. **输油管 输油管**:文本
2. **推广点**: 配置、主题、后增强
3. **存储原始数据**美人鱼不是为了你
4. **清理资源**:内存泄漏是真实的
5. **代表团活动**:改善业绩
6. **多重主题来源**: 站点处理主题的方式不同
7. **时间安排事项**:使用 `requestAnimationFrame`
我在这里所覆盖的所有技术 都用于这个网站的制作和包装 [@ mostlylucid/ permaid- envenancements @ 最优优/ 美人鱼增强](https://www.npmjs.com/package/@mostlylucid/mermaid-enhancements)的完整来源。 [多数是网/多数是网/大多数是美人鱼](https://github.com/scottgal/mostlylucidweb/tree/main/mostlylucid-mermaid).
## 相关员额
- [添加美人鱼。 js 与 htmx](/blog/mermaidandhtmx)
- [为美人鱼切换主题](/blog/switchingthemesformermaid)
- [使用 Pan/Zoom 和 导出加强美人鱼图](/blog/enhancingmermaiddiagramswithpanzoomandexport)
- [作为 npm 软件包的美人鱼增强](/blog/publishingmermaidenhancementsnpm)
## 资源资源资源 资源资源资源 资源资源 资源资源
- [Mermaid.js文件](https://mermaid.js.org/)
- [美人鱼 GitHub](https://github.com/mermaid-js/mermaid)
- [svg-pan-zoom (svg-pan-zoom)](https://github.com/bumbu/svg-pan-zoom)
- [html到图像](https://github.com/bubkoo/html-to-image)
- [我的美人鱼增强一揽子计划](https://www.npmjs.com/package/@mostlylucid/mermaid-enhancements)
尝试上面图表的控件 !