Kompletny przewodnik po diagramach Mermaid.js
Naucz się tworzyć profesjonalne diagramy przy użyciu prostej składni tekstowej
Czym jest Mermaid.js?
Mermaid to narzędzie do tworzenia diagramów i wykresów oparte na JavaScript, które wykorzystuje tekstowe definicje inspirowane Markdownem do dynamicznego tworzenia i modyfikowania diagramów. To projekt open source pozwalający generować diagramy z prostych opisów tekstowych.
Zamiast korzystać ze złożonych narzędzi do rysowania, zapisujesz składnię przypominającą kod, która opisuje diagram, a Mermaid renderuje go jako diagram wizualny. To podejście sprawia, że diagramy można wersjonować, łatwo aktualizować i idealnie nadają się do dokumentacji.
Mermaid bezproblemowo integruje się z platformami dokumentacji, wiki oraz plikami Markdown, dlatego jest ulubionym narzędziem wśród programistów i autorów technicznych.
Dlaczego warto używać Mermaid.js?
- Kontrola wersji: diagramy to pliki tekstowe, więc można je śledzić w Git razem z kodem
- Szybkie aktualizacje: zmień kilka linii tekstu zamiast przerysowywać całe diagramy
- Spójność: Mermaid automatycznie zajmuje się układem i stylem, zapewniając spójne diagramy
- Brak narzędzi graficznych: nie potrzebujesz Visio, Lucidchart ani innych drogich narzędzi
- Dokumentacja jako kod: trzymaj diagramy w tym samym repozytorium co dokumentację
- Wieloplatformowość: działa w przeglądarkach i Node.js oraz integruje się z wieloma platformami
- Darmowe i open source: brak kosztów licencji, aktywna społeczność
- Wiele typów diagramów: obsługuje schematy blokowe, diagramy sekwencji, klas i inne
Obsługiwane typy diagramów
Mermaid obsługuje szeroką gamę typów diagramów, aby sprostać różnym potrzebom dokumentacji:
Schemat blokowy
Wizualizuj przepływy pracy, procesy i drzewa decyzyjne za pomocą węzłów i krawędzi.
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process]
B -->|No| D[Alternative]
C --> E[End]
D --> EZastosowanie: Przepływy procesów, algorytmy, logika decyzyjna
Diagram sekwencji
Pokazuje interakcje między różnymi aktorami lub systemami w czasie.
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request data
API->>DB: Query
DB-->>API: Results
API-->>User: ResponseZastosowanie: Interakcje API, komunikacja systemów, przepływy użytkowników
Diagram klas
Modeluje systemy zorientowane obiektowo z klasami, atrybutami i relacjami.
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- DogZastosowanie: Architektura oprogramowania, projekt OOP, schematy baz danych
Diagram stanów
Przedstawia stany i przejścia w systemie lub procesie.
stateDiagram-v2
[*] --> Idle
Idle --> Loading: Start
Loading --> Success: Complete
Loading --> Error: Fail
Success --> [*]
Error --> Idle: RetryZastosowanie: Maszyny stanów, zarządzanie cyklem życia, stany UI
Diagram ER
Modeluje struktury baz danych i relacje między encjami.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id
string name
string email
}Zastosowanie: Projektowanie baz danych, modelowanie danych, architektura systemu
Wykres Gantta
Planuj i wizualizuj harmonogramy projektów oraz osie czasu.
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2024-01-01, 30d
Development :a2, after a1, 45dZastosowanie: Planowanie projektów, harmonogramy sprintów, roadmapy
Wykres kołowy
Pokazuje proporcjonalne dane i wartości procentowe w formie wizualnej.
pie title Distribution
"Category A" : 42
"Category B" : 30
"Category C" : 28Zastosowanie: Wyniki ankiet, udział w rynku, alokacja zasobów
Graf Git
Wizualizuj strategie rozgałęzień Git i historię commitów.
gitGraph
commit
branch develop
checkout develop
commit
checkout main
merge developZastosowanie: Dokumentacja workflow Git, strategie rozgałęzień
Pierwsze kroki z Mermaid
1. Wybierz typ diagramu
Zacznij od decyzji, który typ diagramu najlepiej przedstawia to, co chcesz pokazać. Każdy typ zaczyna się od konkretnego słowa kluczowego, takiego jak 'flowchart', 'sequenceDiagram' czy 'classDiagram'.
2. Zapisz składnię tekstową
Użyj prostej składni Mermaid, aby opisać swój diagram. Składnia jest intuicyjna i czyta się niemal jak język naturalny. Na przykład 'A --> B' tworzy strzałkę z A do B.
3. Podgląd diagramu
Użyj naszego podglądu online lub dowolnego narzędzia zgodnego z Mermaid, aby zobaczyć diagram renderowany w czasie rzeczywistym. Wprowadzaj poprawki, aż będziesz zadowolony.
4. Eksportuj i udostępniaj
Eksportuj diagram jako SVG lub PNG do prezentacji albo udostępnij URL zespołowi. Możesz też osadzić Mermaid bezpośrednio w plikach Markdown.
Dobre praktyki
- Skupiaj diagramy na jednym koncepcie lub przepływie pracy
- Używaj znaczących etykiet opisujących rzeczywistą logikę biznesową
- Dziel złożone diagramy na mniejsze, połączone ze sobą diagramy
- Dodawaj komentarze z użyciem %%, aby wyjaśniać złożone sekcje
- Stosuj spójne konwencje nazewnictwa w diagramach
- Testuj diagramy w środowisku docelowym przed ich finalizacją
- Dodawaj wskazówki kierunku (TD, LR), aby kontrolować układ, gdy to potrzebne
- Używaj subgraphów do grupowania powiązanych węzłów w schematach blokowych
- Używaj opcji stylu oszczędnie, aby zachować czytelność
- Wersjonuj pliki źródłowe diagramów razem z kodem
Typowe zastosowania
Dokumentacja oprogramowania
Dokumentuj architekturę systemu, przepływy API i interakcje komponentów wraz z kodem.
Planowanie projektów
Twórz wykresy Gantta do planowania sprintów, harmonogramów projektów i alokacji zasobów.
Propozycje techniczne
Wizualizuj proponowane rozwiązania, projekty systemów i decyzje architektoniczne.
Ścieżki użytkownika
Mapuj przepływy użytkowników, doświadczenia klientów i wzorce interakcji.
Projektowanie baz danych
Modeluj relacje encji, struktury schematów i zależności danych.
Dokumentacja procesów
Dokumentuj procesy biznesowe, workflow i standardowe procedury operacyjne.
Materiały edukacyjne
Twórz czytelne, wersjonowane diagramy do tutoriali i kursów technicznych.
Dokumentacja API
Ilustruj przepływy żądanie/odpowiedź, sekwencje uwierzytelniania i interakcje endpointów.
Dodatkowe zasoby
Najczęściej zadawane pytania
Najczęstsze pytania dotyczące korzystania z Mermaid Viewer i tworzenia diagramów
Gotowy na stworzenie pierwszego diagramu?
Wypróbuj naszą darmową internetową przeglądarkę Mermaid i zacznij tworzyć profesjonalne diagramy w kilka minut.
Otwórz Mermaid Viewer