This is a viewer only at the moment see the article on how this works.
To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk
This is a preview from the server running through my markdig pipeline
Mermaid.js Deep Dive: Як це насправді працює і як його розширити
Sunday, 09 November 2025
Введение
NOTE: Це частина моїх експериментів з штучним інтелектом M SK1 спосіб витрачати МSK2 Calude Code Web credits. ЯMSC4 fed this a BUNCH of papers , my understandingMST6 questions I had to generate this articleM ST7 ItM st8 fun and fills a gap I haven’ t seen filled anywhere elseMst10
Цей пост заснований на попередніх статтях: Якщо ви не маєте Додання русалка.js з htmx, Перемикання тем для Сирена, і Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом. Цей глибокий занурення пояснює, що лежить за цими втіленнями
Сирена.js дійсно блискучеMSC1 Написати простий текстM SK2 отримати красиві діаграми. Нічого більше марнувати з Visio чи малювати .ioMST5 втрачати вихідні файли MST6 або підтримувати окремі зображення файлів M ST7 Все живе у значку внизM ST8 версію М ST9 контролювати разом із вашим кодом МST10
Але я хотіла знати як це насправді працює підhood. Як це працюєM SK1
graph LR
A[Text] --> B[Magic?]
B --> C[Beautiful Diagram]
... перетворюється на реальний SVG ? І що важливіше, МSK2 як ви можете під 'єднатися до нього, щоб додати такі funkcje, як panM SK3zoom, перемикання тем МSK5 і виведення funkcjonalnості, яку я створив для цього веб-сайту @влучнішийM SK1морська матка-усилення)?
Після довгого розкопування коду Мерmaid, ' і створення справжніх версій, МSK1 тут, МСК2 - все, що я дізнався про те, як Мерmaid працює всередині і як її правильно розширювати.
Що таке Сирена
Сирена перетворює текстові визначення на діаграми.
Старий спосіб:
- Відкрийте інструмент діаграмування
- Створити діаграму
- Вивезти як PNG
- Вставляйте в Docs
- Потрібно оновити? Знайти джерело файлуM SK1 редагувати, відновити - вивезти МSK4 замінити зображення
Дорога Сирена:
- Написати діаграму в тексті
- Завершено
Обновляйте його? Просто редагуйте текстM SK1 Kontrolа версії ? Це' це лише текст МSK4 працює в значку внизMSC5 Так M SK6
Типи діаграм
Сирена підтримує безглуздо багато типів діаграми:
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...]
Подивіться Доки Сирена для повного списку.
Як насправді працює Сирена?
Ось що відбувається, коли Сирена робить діаграму
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: визначення тексту
Все починається з тексту. Ви пишете діаграми в Мермейді 's DSL M SK2домені МSK3конкретній мові
// Flowchart
const diagram = `
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug time]
`;
Шаг 2: Lexical Analysis
Ліксер розділяє текст на символи.
A[Start] --> B{Decision}
Стає символами, такими як:
[
{ 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: Parsing і генерування AST
Програміст споживає символи і створює абстрактне дерево синтаксису (ASTM SK1
// 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' }
]
}
Сирена використовує різні аналітики для кожного типу діаграми. Вони часто генеруються з файлів граматики, використовуючи Джисон (подібно до Yacc
Шаг 4: Виявление діаграми
Сирена розпізнає тип діаграми з першої лінії:
// 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: ТипМSK1конкретне відображання
Кожен тип діаграми має власний рендерер. Рендерер бере AST і генерує SVG елементи.
Для схем потоку, Сирена використовує Даґре bibliotekа для графічного макету. Для іншихM SK1 він використовує індивідуальні алгоритми або бібліотеки, такі як Cytoscape.
// 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:
<svg xmlns="http://www.w3.org/2000/svg">
<g class="node">
<rect x="0" y="0" width="100" height="50"/>
<text x="50" y="25">Start</text>
</g>
<g class="edge">
<path d="M 100 25 L 200 25" stroke="#333"/>
</g>
</svg>
Шаг 7: Введення DOM
Сирена знаходить все .mermaid і замінює їх рендерованими SVG:
// 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: Пост МSK1 Процедура МSK2 Де ви приходите )
Після того, як Сирена вставляє SVG, ви можете покращити йогоM SK1 Ось тут всі мої покращення закріплені в:
- Функція Pan/zoom
- Кнопка управління
- Виведення можливостей
- Перемикання тем
Більше про це внизу.
Розширювання Mermaid: Показів розширення
Тепер, коли ми знаємо, як працює Сирена, ми можемо дослідити, як її розширити.
1. Налаштування
Найпростіший варіант - це конфігурація:
import mermaid from 'mermaid';
mermaid.initialize({
startOnLoad: true,
theme: 'dark',
securityLevel: 'loose',
flowchart: {
curve: 'basis',
padding: 15
}
});
2. Customization Theme
Я розповідав про це в Перемикання тем для СиренаМСК0 , але тут "'" є ключовим кроком .
Проблема з переключенням тематики
Сирена повинна бути inicialізована з темою, і ви можетеMSC1 не змінювати її після., але якщо ви хочете переробитиM SK3 представити діаграми з новою темою doesn' не зберігає в DOM.
Рішення
Поміщайте оригінальний контент перед тим, як відтворювати, тоді відновіть і відтворюйтеM SK1 відтворити при переключенні тем
// 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;
}
}
};
Metodи виявлення багатьох тем (сайти обробляють тему по-іншому ):
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';
}
Подивіться повний код перемикача тем для деталей.
МSK0 Пост-Позитивні покращення
Ось де відбувається справжня магія.
Я розповідав про це в Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом, тож я ' розповім про ключові прийоми
Згортання діаграм
Створити контейнер для упаковок для управління:
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;
}
Додаємо Pan/Zoom
Використовуючи svg-panM SK1zoom:
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;
}
Кнопка управління
Створити плавучу панель управління:
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);
}
Делегація на події (Performance!)
Don' не прив 'язувати слухачів кожнісіньким кнопкамM SK1 використовувати делегацію подій:
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
}
});
Виведення функцій
Виклик Elementи SVG мають динамічне розмірування, панельM SK1 трансформації зйомки , і успадковані стилі. Для правильного виведенняMSC4 вам потрібноMSSK5
- Клоні SVG
- Захищати виміри
- Перетвори
- Перетворити на PNG або SVG
Використовуючи html-наM SK1зображення:
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);
}
Критичні деталі:
- Запам 'ятайте ViewBox - Захоплює всю діаграмуM SK1 не лише видиму частину
- Офф-рендерінг екрану - уникати впливу на представлену діаграму
- Рatio пікселів: M SK1 - WysokiM SK1DPI для крихітного експорту ПНГ
Подивіться повний код eksportу для більших деталей.
Повний пакет покращення
Я пакував всі ці покращення, як @влучнішийM SK1морська матка-усилення. Подивіться Опублікувати покращення для морської дівчини як пакет npm для повних деталей.
Ось як це все працює.
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
Використовування
npm install @mostlylucid/mermaid-enhancements
import { init } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
await init();
Те, що МСК0 , це "!". Ваші діаграми Сирена тепер мають МСК2 .
- ✅ Interactive panM SK1zoom
- ✅ Світлоbox на весь екран
- ✅ PNGM SK1SVG
- ✅ Автоматичний перемикач тем
- ✅ Реакційний дизайн
Інтеграція з HTMX
Як я описав Додання русалка.js з htmx, вам потрібно перезапустити МSK1ініціалізувати Мермейду після обміну контентом HTMX
// On page load
document.addEventListener('DOMContentLoaded', function () {
mermaid.initialize({ startOnLoad: true });
});
// After HTMX swaps content
document.body.addEventListener('htmx:afterSwap', function(evt) {
mermaid.run();
});
З пакетом покращень:
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
});
Найкращі практики, які я вивчив
Після того, як я збудував цю штуку і виправив дивні краєвидні cases,
1. Знову зберігати оригінальний контент
Сирена не зберігає оригінального джерела діаграми після відтворення.
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. Почистити інстанції
Потіки пам 'яті є справжніми. Зруйнуйте instanції перед створенням нових:
if (panZoomInstances.has(id)) {
try {
panZoomInstances.get(id).destroy();
} catch (e) {
console.warn('Failed to destroy:', e);
}
panZoomInstances.delete(id);
}
3. Використовуйте delegatію подій
Не прикріпляйте слухачів до окремих кнопок:
// ❌ 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. Ручка
Ракетний Лодер затягує виконання JavaScript. Почекайте на залежністьM SK1
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();
});
}
І виключити вашу головну стрічку з Rocket Loader
<script src="main.js" data-cfasync="false"></script>
5. Час - це все
Використовувати requestAnimationFrame для кращого часу, ніж довільний setTimeout:
// After Mermaid renders
await mermaid.run();
// Wait for paint before enhancing
await new Promise(resolve => {
requestAnimationFrame(() => {
requestAnimationFrame(() => {
enhanceMermaidDiagrams();
resolve();
});
});
});
6. Охоронний SVG Рух
SVGs можуть бути дивними. Звісно перевіряйтеM SK1
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}`;
}
Вказівки для розв 'язання проблем
Виход Konsolи
З правильною ініціалізацією, треба побачитиM SK1
Saving original data
Loading mermaid with theme: dark
Mermaid initialized
Enhanced 3 diagrams
Випробовування списку перевірок
Після втілення покращень:
- Діаграми відтворюють на завантаження сторінки
- ПанM SK1навігальне управління
- Полний екран відкривається МSK1 закривається МSK2XM SK3 натискає назовні , ESC)
- Eksport PNG захоплює повну діаграму
- Eksport SVG зберігає вектори
- Працює після обміну контентом HTMX
- Перемикання тем reM SK1правильна
- мобільний реагуючий
- Темний стиль
- Доступність клавіатура
Поширені проблеми
Грамматика не відображається:
- Подивіться на консоль браузера на помилки
- Перевірити завантаження Сирена (
window.mermaid) - Проверка синтаксису діаграми
Пан/зом не працюєM SK1
- Перевірити інициалізацію svg-panM SK1zoom
- Проверка конфлікту CSS (
pointer-events: none) - Проаналізувати карту інстанцій
Виведення захоплює лише куток:
- Не вистачає збереження viewBox
- Перетворення не видалено
- Проверка логіки клонування
Тема не змінюється:
- Початкові дані не заpisane
data-processedне відновити- Слухачі подій не зареєстровані
Рівень ефективності
Зачаток ліни
Допоки не потрібне, не вдосконалювати навантаження'
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 });
Обсерватор перехрестя
Рендерувати діаграми тільки тоді, коли вони помітні:
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);
});
Викидати позиціонери
Під час зміни розміру або теми:
let timeout;
window.addEventListener('resize', () => {
clearTimeout(timeout);
timeout = setTimeout(() => {
panZoomInstances.forEach(instance => {
instance.resize();
instance.fit();
});
}, 250);
});
На завершення
Mermaid.js - це фантастична річ, яка виходить з коробки , але розуміння того, як вона працює всередині, дає вам змогу побудувати справді круті покращення.
- Рендерування ланцюга: Текст → Лексер МSK2 Розшифровувач МSK3 AST M→ Рендер МСК5 SVG
- Точки розширення: Конфигурація МSK1 Теми МSK2 пост - покращення передачі
- Поміщати оригінальні дані: Сирена не робить цього для вас
- Чисти ресурси: Потік пам 'яті реальний
- Відповідання про події: Кращі результати
- Багато джерел тем: Вебсайти обробляють тему по-різному
- Справа в часі: Використовувати
requestAnimationFrame
Всі методи, які я описав тут, використовуються для виробництва на цьому сайті і упаковані в @влучнішийM SK1морська матка-усилення. Полне джерело доступно на більшістьlucidweb/mostlylucid-mermaid.
Подібні статті
- Додання русалка.js з htmx
- Перемикання тем для Сирена
- Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом
- Опублікувати покращення для морської дівчини як пакет npm
Ресурс
- Сирена.js Dokumentacja
- Mermaid GitHub
- svg-panM SK1zoom
- html-наM SK1зображення
- Моя Сирена Поліпшення Пакет
Попробуйте контролювати на діаграмі вище! M SK1