Back to "Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом"

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

DaisyUI Javascript Mermaid SVG Tailwind

Поліпшувати діаграми Сирени з Pan/Zoom і Eksportом

Friday, 07 November 2025

Введение

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, але все ж читають

mermaid_pan_zoom.png

Проблема

З-за коробки, Діаграми Сирени мають декілька обмеженьM SK1

  1. Фиксований розмір - Великі діаграми або відрізані, або зменшені до потрібного розміру
  2. Немає інтерактивності - МожнаM SK1 не збільшувати, щоб побачити деталі, або розкрутити
  3. Ніяких вивезень - Пользовачі не можуть ' зберігати діаграми для зовнішнього використання
  4. Поганий досвід мобільного зв 'язку - Малі екрани роблять складні діаграми непотрібними
  5. Проблеми переключення тем - 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 - Интерактивна панель та збільшення для елементів SVG
  • html-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');
    }
}

Найважливіші умови для експорту:

  1. Запам 'ятайте ViewBox - Критичний для захоплення всієї діаграми , не тільки видимої частини
  2. Вирахувати виміри - Уявно встановити ширину / висоту з viewBox для послідовного eksportу
  3. Перетвори - Стріп-пан МSK1зом трансформує так, що eksport показує повну діаграму
  4. Керування фоном - Білий фон для PNG , прозорий для SVG
  5. високий рівень роздільності - Використовувати 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 ввести для активації)

Рівень ефективності

  1. Повільна інициалізація - Тільки покращити діаграми, які існують на сторінці
  2. Виczyszczenie инстанцій - Зруйнувати інстанції панM SK1zoom, коли знімають діаграми
  3. Делегація подій - Single click listener об 'єднує всі кнопки управління
  4. requestAnimationFrame - Краще налаштування часу, ніж вибірка
  5. Оборотні експорти - Захищати швидке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

Спробуйте натиснути на управління на діаграмі вище!

logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.