Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом
Введение
Pakiet npm доступний: Ця інсталяція доступна @влучнішийM SK1морська матка-усилення - виробництво - готовий пакет npm МSK2 Погляньте Опублікувати покращення для морської дівчини як пакет npm подивіться, як його використовувати в проектах.
Сирена - це чудовий інструмент для створення діаграм з тексту, але по замовчуванню вона може бути обмежена для складних діаgramів . Пользовачі не можуть' легко збільшувати зображення, щоб побачити деталіM SK3 розкрутити великі діаграмиMSC4 або вивезти їх для документаціїМSK5 В цьому artykuleMska6 ЯMske7 покажу вам, як я покращив Сиренкові діаграмі на цій сайті з інтерактивним збільшеннямMSKA8 контролі збільшуванняMСК9 перегляд люксового вікна на повному екраніМСК10 і функцію eksportу M СК11 в обох форматах PNG та SVG МСК12
Ця інсталяція - виробництво- готовийM SK1 граційно облаштовує перемикання в темний режим , і стійка до перешкоди Cloudflare Rocket Loader
Як це виглядає
Отже, ми хочемо мати ось це: МСК1 - гарне зображення на сторінці, МСК2 - випливає звідти, МSK3 - русалка, . - JavaScript показує, що МСК5 схоже на GitHub, але краще. Це означає, що діаграми не сприймають SCREENS, але все ж читають

Проблема
З-за коробки, Діаграми Сирени мають декілька обмеженьM SK1
- Фиксований розмір - Великі діаграми або відрізані, або зменшені до потрібного розміру
- Немає інтерактивності - МожнаM SK1 не збільшувати, щоб побачити деталі, або розкрутити
- Ніяких вивезень - Пользовачі не можуть ' зберігати діаграми для зовнішнього використання
- Поганий досвід мобільного зв 'язку - Малі екрани роблять складні діаграми непотрібними
- Проблеми переключення тем - Diagrams don 't always reM SK2render correctly when switching between light and dark mode
Рішення
I' запровадила комплексну систему покращення, яка додає
- Інтерактивний пан/zoom за допомогою бібліотеки svg-panM SK1zoom
- Рухливі кнопки управління для збільшення
- Світлоbox на повному екрані режим для кращого перегляду
- Виведення PNG та SVG функціональність
- Auto- підходить до навантаження так що ціла діаграма є видимою по замовчуванню
- Полний-вигин дисплея видалення штучних обмежень розміру
Уявлення про архітектуру
Рішення складається з трьох основних компонентів:
graph TB
A[mermaid_theme_switch.js] -->|Initializes| B[Mermaid Diagrams]
B -->|Renders SVG| C[mermaid_enhancements.js]
C -->|Adds| D[Control Buttons]
C -->|Initializes| E[svg-pan-zoom]
D -->|Triggers| F[Pan/Zoom Actions]
D -->|Triggers| G[Export Functions]
D -->|Triggers| H[Fullscreen Lightbox]
Втілення
Установлення залежностей
Перше, заinstalувати необхідні npm пакети :
npm install svg-pan-zoom html-to-image
Ці бібліотеки забезпечують:
svg-pan-zoom- Интерактивна панель та збільшення для елементів SVGhtml-to-image- Виведення SVGM SK1 Функція PNG
Модуль покращення ядро
Головний модуль покращення (mermaid_enhancements.js) управляє усіма інтерактивними функціями
Створювання кнопок управління
Кожна діаграма отримує плавну панель управління з кнопками для всіх дій:
function createControlButtons(container, diagramId) {
// Check if controls already exist
if (container.querySelector('.mermaid-controls')) {
return;
}
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 View', action: 'reset' },
{ icon: 'bx-move', title: 'Pan', action: 'pan' },
{ icon: 'bx-image', title: 'Export as PNG', action: 'exportPng' },
{ icon: 'bx-code-alt', title: 'Export as SVG', action: 'exportSvg' }
];
buttons.forEach(btn => {
const button = document.createElement('button');
button.className = `mermaid-control-btn bx ${btn.icon}`;
button.setAttribute('title', btn.title);
button.setAttribute('aria-label', btn.title);
button.setAttribute('data-action', btn.action);
button.setAttribute('data-diagram-id', diagramId);
controlsDiv.appendChild(button);
});
container.appendChild(controlsDiv);
}
Початок роботи Pan/Zoom
Бібліотека svg-panM SK1zoom zapewnia гладку , ефективну взаємодію:
function initPanZoom(svgElement, diagramId) {
// Clean up existing instance if present
if (panZoomInstances.has(diagramId)) {
try {
panZoomInstances.get(diagramId).destroy();
} catch (e) {
console.warn('Failed to destroy existing pan-zoom instance:', e);
}
panZoomInstances.delete(diagramId);
}
try {
const panZoomInstance = svgPanZoom(svgElement, {
zoomEnabled: true,
controlIconsEnabled: false, // We use custom controls
fit: true,
center: true,
minZoom: 0.1,
maxZoom: 10,
zoomScaleSensitivity: 0.3,
dblClickZoomEnabled: true,
mouseWheelZoomEnabled: true,
preventMouseEventsDefault: true,
contain: false
});
panZoomInstances.set(diagramId, panZoomInstance);
return panZoomInstance;
} catch (error) {
console.error('Failed to initialize pan-zoom:', error);
return null;
}
}
Виведення функцій
Система eksportу зберігає якість діаграми і обробляє як формати PNG, так і SVG:
async function exportDiagram(container, format, diagramId) {
try {
const svgElement = container.querySelector('svg');
if (!svgElement) {
window.showToast && window.showToast('No diagram found to export', 3000, 'error');
return;
}
// Clone the SVG to avoid modifying the original
const clonedSvg = svgElement.cloneNode(true);
// Get the viewBox or calculate from bounding box
let viewBox = clonedSvg.getAttribute('viewBox');
if (!viewBox) {
const bbox = svgElement.getBBox();
viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
clonedSvg.setAttribute('viewBox', viewBox);
}
// Parse viewBox to get dimensions
const [, , vbWidth, vbHeight] = viewBox.split(' ').map(Number);
// Set explicit dimensions based on viewBox for proper export
clonedSvg.setAttribute('width', vbWidth);
clonedSvg.setAttribute('height', vbHeight);
// Remove inline styles but keep viewBox
clonedSvg.removeAttribute('style');
clonedSvg.style.backgroundColor = 'transparent';
clonedSvg.style.maxWidth = 'none';
// Create temporary container
const tempDiv = document.createElement('div');
tempDiv.style.position = 'absolute';
tempDiv.style.left = '-9999px';
tempDiv.appendChild(clonedSvg);
document.body.appendChild(tempDiv);
let dataUrl;
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const filename = `mermaid-diagram-${timestamp}`;
if (format === 'png') {
dataUrl = await toPng(clonedSvg, {
backgroundColor: 'white',
pixelRatio: 2 // Higher quality
});
downloadFile(dataUrl, `${filename}.png`);
} else {
dataUrl = await toSvg(clonedSvg, {
backgroundColor: 'transparent'
});
downloadFile(dataUrl, `${filename}.svg`);
}
// Clean up
document.body.removeChild(tempDiv);
window.showToast && window.showToast(`Diagram exported as ${format.toUpperCase()}`, 3000, 'success');
} catch (error) {
console.error('Failed to export diagram:', error);
window.showToast && window.showToast('Failed to export diagram', 3000, 'error');
}
}
Найважливіші умови для експорту:
- Запам 'ятайте ViewBox - Критичний для захоплення всієї діаграми , не тільки видимої частини
- Вирахувати виміри - Уявно встановити ширину / висоту з viewBox для послідовного eksportу
- Перетвори - Стріп-пан МSK1зом трансформує так, що eksport показує повну діаграму
- Керування фоном - Білий фон для PNG , прозорий для SVG
- високий рівень роздільності - Використовувати
pixelRatio: 2для крихітного експорту ПНГ
Світлоbox на повному екрані
Світлоbox дає захоплююче відчуття перегляду:
function openFullscreenLightbox(container, diagramId) {
const svgElement = container.querySelector('svg');
if (!svgElement) return;
// Create lightbox overlay
const lightbox = document.createElement('div');
lightbox.className = 'mermaid-lightbox';
lightbox.innerHTML = `
<div class="mermaid-lightbox-content">
<button class="mermaid-lightbox-close bx bx-x" aria-label="Close"></button>
<div class="mermaid-lightbox-diagram-wrapper">
<div class="mermaid-lightbox-diagram"></div>
</div>
</div>
`;
// Clone and prepare SVG
const clonedSvg = svgElement.cloneNode(true);
clonedSvg.removeAttribute('width');
clonedSvg.removeAttribute('height');
clonedSvg.style.width = '100%';
clonedSvg.style.height = '100%';
const diagramContainer = lightbox.querySelector('.mermaid-lightbox-diagram');
diagramContainer.appendChild(clonedSvg);
// Add controls to lightbox
const wrapper = lightbox.querySelector('.mermaid-lightbox-diagram-wrapper');
const lightboxDiagramId = `${diagramId}-lightbox`;
createControlButtons(wrapper, lightboxDiagramId);
document.body.appendChild(lightbox);
// Initialize pan-zoom after layout completes
setTimeout(() => {
const panZoom = initPanZoom(clonedSvg, lightboxDiagramId);
if (panZoom) {
panZoom.resize();
panZoom.fit();
panZoom.center();
}
}, 100);
// Close handlers
const closeLightbox = () => {
if (panZoomInstances.has(lightboxDiagramId)) {
try {
panZoomInstances.get(lightboxDiagramId).destroy();
} catch (e) {
console.warn('Failed to destroy lightbox pan-zoom:', e);
}
panZoomInstances.delete(lightboxDiagramId);
}
lightbox.remove();
};
lightbox.querySelector('.mermaid-lightbox-close').addEventListener('click', closeLightbox);
lightbox.addEventListener('click', (e) => {
if (e.target === lightbox) closeLightbox();
});
// ESC key to close
const escHandler = (e) => {
if (e.key === 'Escape') {
closeLightbox();
document.removeEventListener('keydown', escHandler);
}
};
document.addEventListener('keydown', escHandler);
}
Основною функцією покращення
Це пов 'язує все разом і називається після Mermaid renders:
export function enhanceMermaidDiagrams() {
const diagrams = document.querySelectorAll('.mermaid[data-processed="true"]');
diagrams.forEach(diagram => {
const svgElement = diagram.querySelector('svg');
if (!svgElement) return;
// CRITICAL: Remove inline max-width constraint that Mermaid adds
svgElement.style.maxWidth = 'none';
// Wrap diagram with controls
const diagramId = wrapDiagramWithControls(diagram);
// Initialize pan/zoom and auto-fit
const panZoom = initPanZoom(svgElement, diagramId);
if (panZoom) {
// Fit diagram to container by default
setTimeout(() => {
panZoom.resize();
panZoom.fit();
panZoom.center();
}, 100);
}
});
// Set up event delegation for control buttons (only once)
if (!document.body.hasAttribute('data-mermaid-controls-initialized')) {
document.body.addEventListener('click', handleControlClick);
document.body.setAttribute('data-mermaid-controls-initialized', 'true');
}
}
Критична поправка: Сирена застосовує вказівку style="max-width: 1020px" до елементів SVG, що запобігає повному показуM SK1широта表示у . Вилуczenie цього є необхідним для правильного реагування
Інтеграція тем
Перемикач тем гарантує, що діаграми відображаються правильно при переключенні між світловим і темним режимами.
import { enhanceMermaidDiagrams } from './mermaid_enhancements';
const loadMermaid = async (theme) => {
if (!window.mermaid) return;
try {
window.mermaid.initialize({
startOnLoad: false,
theme,
themeVariables: {
background: 'transparent'
}
});
await window.mermaid.run({
querySelector: elementSelector,
});
// Enhance diagrams after rendering completes
// Use requestAnimationFrame for better timing
await new Promise(resolve => {
requestAnimationFrame(() => {
requestAnimationFrame(() => {
enhanceMermaidDiagrams();
resolve();
});
});
});
} catch (err) {
console.error('Mermaid render error:', err);
}
};
Використовуючи requestAnimationFrame двічі гарантує, що браузер закінчив малювати SVG перед тим, як ми спробуємо покращити його.
Компatibility Rocket Loader Cloudflare
Cloudflare's Rocket Loader can delay JavaScript execution , breaking initializationM SK2 Here's the bulletproof solution МSK4
// Wait for all dependencies to load with exponential backoff
function waitForDependencies(maxAttempts = 50) {
return new Promise((resolve) => {
let attempts = 0;
const checkDependencies = () => {
attempts++;
const depsReady =
typeof window.hljs !== 'undefined' &&
typeof window.mermaid !== 'undefined' &&
typeof window.Alpine !== 'undefined' &&
typeof window.htmx !== 'undefined';
if (depsReady) {
console.log('All dependencies loaded after', attempts, 'attempts');
// Start Alpine.js now that it's loaded
if (window.Alpine && !window.Alpine.version) {
try {
window.Alpine.start();
console.log('Alpine.js started');
} catch (err) {
console.error('Failed to start Alpine:', err);
}
}
resolve();
} else if (attempts >= maxAttempts) {
console.warn('Timeout waiting for dependencies');
resolve(); // Continue anyway
} else {
// Retry with exponential backoff
const delay = Math.min(50 * Math.pow(1.2, attempts), 500);
setTimeout(checkDependencies, delay);
}
};
checkDependencies();
});
}
// Robust initialization
async function safeInitialize() {
try {
await waitForDependencies();
if (document.readyState === 'loading') {
await new Promise(resolve => {
document.addEventListener('DOMContentLoaded', resolve, { once: true });
});
}
await initializePage();
} catch (err) {
console.error('Failed to initialize page:', err);
// Retry once after delay
setTimeout(() => {
initializePage().catch(e => console.error('Retry failed:', e));
}, 1000);
}
}
safeInitialize();
Також переконайтесь, що ваш головний скрипт має data-cfasync="false" атрибут exclude it from Rocket Loader:
<script src="~/js/dist/main.js" type="module" asp-append-version="true" data-cfasync="false"></script>
Стіллінг з Tailwind/DaisyUI
CSS використовує класи Tailwind і налаштування дизайну для поліша:
/* Mermaid diagram wrapper */
.mermaid-wrapper {
@apply relative rounded-lg overflow-hidden w-full;
margin: 1rem 0;
}
.mermaid-wrapper .mermaid {
@apply m-0 w-full;
min-height: 500px;
display: flex;
align-items: center;
justify-content: center;
padding: 1rem;
}
.mermaid-wrapper .mermaid svg {
width: 100% !important;
height: auto !important;
min-height: 450px;
}
/* Control buttons */
.mermaid-controls {
@apply absolute top-2 right-2 flex gap-1 z-10;
background: rgba(255, 255, 255, 0.9);
border-radius: 0.5rem;
padding: 0.25rem;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
.dark .mermaid-controls {
background: rgba(31, 41, 55, 0.95);
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
}
.mermaid-control-btn {
@apply p-2 rounded cursor-pointer transition-all duration-200;
background: transparent;
border: none;
color: #4b5563;
font-size: 1.25rem;
display: flex;
align-items: center;
justify-content: center;
width: 2rem;
height: 2rem;
}
.mermaid-control-btn:hover {
background: rgba(37, 99, 235, 0.1);
color: #2563eb;
transform: scale(1.1);
}
.dark .mermaid-control-btn {
color: #9ca3af;
}
.dark .mermaid-control-btn:hover {
background: rgba(55, 65, 81, 0.8);
color: #60a5fa;
}
/* Lightbox */
.mermaid-lightbox {
@apply fixed inset-0 z-50 flex items-center justify-center;
background: rgba(0, 0, 0, 0.85);
backdrop-filter: blur(4px);
animation: fadeIn 0.2s ease-out;
}
.dark .mermaid-lightbox {
background: rgba(0, 0, 0, 0.95);
}
.mermaid-lightbox-content {
@apply relative w-11/12 h-5/6 bg-white rounded-lg shadow-2xl;
max-width: 1400px;
}
.dark .mermaid-lightbox-content {
@apply bg-gray-800;
}
.mermaid-lightbox-close {
@apply absolute top-4 right-4 z-10 p-2 rounded-full cursor-pointer transition-all;
background: rgba(0, 0, 0, 0.5);
border: none;
color: white;
font-size: 2rem;
width: 3rem;
height: 3rem;
display: flex;
align-items: center;
justify-content: center;
}
.mermaid-lightbox-close:hover {
background: rgba(220, 38, 38, 0.8);
transform: scale(1.1);
}
@keyframes fadeIn {
from { opacity: 0; }
to { opacity: 1; }
}
Тестування і виправлення
Ось як перевірити роботу всього'
Виход Konsolи
З правильною ініціалізацією, треба побачитиM SK1
All dependencies loaded after 1 attempts
Alpine.js started
Highlight.js copy plugin registered
Highlight.js initialized on page load
Mermaid initialized on page load
Document is ready - all initializations complete
HTMX event listener registered successfully
Динамічний контент HTMX
Після обміну HTMX, ви маєте побачитиM SK1
HTMX afterSettle triggered for: contentcontainer
Highlight.js applied after HTMX swap
Mermaid initialized
Mermaid applied after HTMX swap
HTMX afterSettle complete for: contentcontainer
Випробовування списку перевірок
- Діаграми відтворюють на першій завантаження сторінки
- ПанM SK1навігальне управління
- Світлоbox на повному екрані відкривається і закривається
- Виведення ПНГ бере повну діаграму МSK1 не тільки кут МSK2
- Eksport SVG зберігає вектори
- Працює після обміну контентом HTMX
- Перемикання тем reM SK1правильно віддає діаграми
- мобільний реагуючий МSK1 контроль лишається видимим МSK2 діаграми масштабу )
- Штунок в темному режимі працює правильно
- Доступність до клавіатури МSK1таб для управлінняM SK2 ввести для активації)
Рівень ефективності
- Повільна інициалізація - Тільки покращити діаграми, які існують на сторінці
- Виczyszczenie инстанцій - Зруйнувати інстанції панM SK1zoom, коли знімають діаграми
- Делегація подій - Single click listener об 'єднує всі кнопки управління
- requestAnimationFrame - Краще налаштування часу, ніж вибірка
- Оборотні експорти - Захищати швидкеM SK1виведення спалахів
Компatybilність браузера
Випробовували і працювали над:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Мобільні браузери (iOS SafariM SK1 Chrome Mobile)
IE11 не підходить завдяки сучасним JavaScript-можливим характеристикам (constM SK1 стрілкові функції, асинк /await МSK4 запросАнімаціяFrame
Завершення
Цей комплексний покращення перетворює статичні діаграми Сирени на інтерактивні, экспортні візуалізаціїM SK1 Втілення є виробництвом- готовим , гнучким до крайних коробокMSC4 і надає чудовий досвід для користувачаМSK5
Key takeaways:
- Зніміть Mermaid's в лінію
max-widthобмеження для diagramів повної ширини- - Запам 'ятайте ViewBox, коли ви exportуєте цілий діаграми
- Використовуйте requestAnimationFrame для таймінгу замість произвольного затримки
- Рухати Cloudflare Rocket Loader з перевіркою залежності та логікою повторення
- Дайте багато способів замкнути коробку для світла ( кнопка , клацання назовніM SK2 ESC)
- Використовувати делегування подій для виконання з багатьма діаграмами
Використовуючи пакет npm
Замість копіювання коду, ви можете зараз заinstalувати цю функцію як пакет npmM SK1
npm install @mostlylucid/mermaid-enhancements
import { init } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
await init();
Подивіться Опублікувати покращення для морської дівчини як пакет npm для всієї документації, приклади інтеграції фреймворкаM SK1 і заawansовані варіанти конфігурації .
Полний вихідний код також доступний в цьому блогі' в базі даних на Mostlylucid/src/js/mermaid_enhancements.js і як open-source npm пакет на більшістьlucidweb/mostlylucid-mermaid.
Ось приклад діаграми
Ось складний приклад, який показує архітектуру цього блогу:
graph TB
subgraph Client["Client Browser"]
A[User Request] -->|HTMX| B[Blog Controller]
B -->|Cache Miss| C[Blog Service]
C -->|File Mode| D[Markdown Service]
C -->|DB Mode| E[EF Core Context]
D -->|Parse| F[Markdig Pipeline]
F -->|Render| G[HTML + Mermaid]
E -->|Query| H[PostgreSQL]
H -->|Full-Text Search| I[GIN Index]
G -->|Enhance| J[mermaid_enhancements.js]
J -->|Initialize| K[svg-pan-zoom]
J -->|Add| L[Control Buttons]
L -->|Export| M[html-to-image]
end
subgraph Background["Background Services"]
N[File Watcher] -->|Change Detected| O[Saves to DB]
O -->|Trigger| P[Translation Service]
P -->|Batch| Q[EasyNMT API]
Q -->|12 Languages| R[Translated Files]
end
style A stroke:#22c55e,stroke-width:3px,color:#4ade80
style G stroke:#3b82f6,stroke-width:3px,color:#60a5fa
style J stroke:#f59e0b,stroke-width:3px,color:#f59e0b
style K stroke:#ec4899,stroke-width:3px,color:#ec4899
style M stroke:#8b5cf6,stroke-width:3px,color:#8b5cf6
Спробуйте натиснути на управління на діаграмі вище!