Obsługa Mermaid

Diagrammix3 obsługuje importowanie i eksportowanie diagramów przy użyciu składni Mermaid, popularnego języka diagramowania opartego na tekście.

Czym jest Mermaid?

Mermaid to narzędzie do tworzenia diagramów oparte na JavaScript, które używa składni podobnej do Markdown do definiowania diagramów. Jest powszechnie stosowane w dokumentacji, wiki i plikach README.

Przykładowa składnia Mermaid:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Importowanie diagramów Mermaid

Uwaga: Import i eksport Mermaid są funkcją PRO.

Wstaw Mermaid (z podglądem i weryfikacją)

Najszybszym sposobem na przeniesienie Mermaid na obszar roboczy jest panel Wstaw Mermaid, który wyświetla podgląd i weryfikuje diagram przed umieszczeniem czegokolwiek.

1. Przejdź do Edycja → Wstaw Mermaid
2. Wklej lub wpisz składnię Mermaid w edytorze
3. Podczas pisania Diagrammix weryfikuje składnię na żywo i pokazuje:
   • czy diagram jest prawidłowy
   • wykryty typ diagramu
   • liczbę węzłów i łączników
   
   Błędy są oznaczane bezpośrednio w edytorze, dzięki czemu możesz je naprawić, zanim trafią na obszar roboczy.
4. Kliknij Zastosuj, aby umieścić diagram, lub Anuluj, aby odrzucić

Wklejanie Mermaid ze schowka przechodzi przez tę samą weryfikację, więc niepoprawna składnia nigdy nie generuje uszkodzonego diagramu.

Uwaga: Mermaid importuje się poprzez wklejanie lub wpisywanie w panelu Wstaw Mermaid — nie ma osobnego polecenia „importuj plik". Aby przenieść plik .mmd, otwórz go w dowolnym edytorze tekstu i wklej jego zawartość.

Obsługiwane typy diagramów

Diagrammix rozpoznaje szeroką gamę typów diagramów Mermaid, w tym:

Pozostałe typy Mermaid (oś czasu, user journey, quadrant, wykres XY, Sankey, Graf Git i inne) są rozpoznawane i importowane, ale renderują się jako ogólny graf węzłów i łączników, a nie wyspecjalizowany układ. Panel Wstaw Mermaid informuje o wykrytym typie przed zastosowaniem.

Składnia diagramu stanów

Diagramy stanów modelują stany, w jakich może znajdować się obiekt, oraz przejścia między stanami.

Podstawowy diagram stanów:

stateDiagram-v2
    [*] --> Active
    Active --> Inactive : deactivate
    Inactive --> Active : activate
    Active --> [*] : terminate

Stany i przejścia:

• [*] reprezentuje stany początkowe i końcowe
• --> tworzy strzałkę przejścia
• : etykieta dodaje etykiety przejść
• Zagnieżdżone stany używają wcięć

Stany złożone:

stateDiagram-v2
    state Processing {
        [*] --> Validating
        Validating --> Executing
        Executing --> [*]
    }

Wynik: Diagram maszyny stanowej z właściwymi kształtami stanów i oznaczonymi przejściami.

Przykłady importu

Schemat blokowy

Wejście Mermaid:

flowchart TD
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Wynik: Schemat blokowy od góry do dołu z kształtami prostokąta, zaokrąglonego prostokąta i rombu połączonymi oznaczonymi strzałkami.

Diagram sekwencji

Wejście Mermaid:

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!

Wynik: Diagram sekwencji z dwoma uczestnikami i strzałkami wiadomości.

Diagram klas

Wejście Mermaid:

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()

Wynik: Diagram klas UML z relacjami dziedziczenia.

Eksportowanie do Mermaid

Kopiuj Mermaid

Diagrammix eksportuje do Mermaid przez schowek — nie ma osobnego polecenia „eksportuj do pliku".

1. Zaznacz kształty, które chcesz wyeksportować, lub nie zaznaczaj niczego, aby wyeksportować cały obszar roboczy
2. Przejdź do Edycja → Kopiuj Mermaid
3. Wklej składnię Mermaid tam, gdzie jej potrzebujesz (a następnie zapisz ją jako plik .mmd, jeśli chcesz)

Eksport dostosowuje się do tego, co znajduje się w zakresie: mapa myśli jest kopiowana jako składnia mindmap, a strona klasy lub sekwencji UML jako classDiagram / sequenceDiagram; wszystko inne jest eksportowane jako flowchart.

Kontynuuj edycję w Mermaid (pełny obieg)

Zaimportowane diagramy Mermaid zachowują swoje źródło, więc możesz nadal pracować w notacji Mermaid zamiast edytować kształty jeden po jednym.

1. Zaznacz zaimportowany diagram Mermaid
2. Kliknij przycisk </> (Edytuj źródło Mermaid) na diagramie
3. Otwiera się panel Edytuj źródło Mermaid z oryginalnym tekstem Mermaid wstępnie wypełnionym
4. Edytuj tekst i przerenderuj, aby zaktualizować diagram w miejscu

Jeśli Twoje zmiany wpłynęłyby na strukturę diagramu (na przykład usunięcie węzłów, od których zależą inne elementy), panel wyświetla te niezgodności z wyprzedzeniem, abyś mógł zdecydować przed zatwierdzeniem.

Edytowanie jako natywne obiekty

Możesz również edytować zaimportowany diagram bezpośrednio jako natywne obiekty Diagrammix:

• Przenoś i zmieniaj rozmiar kształtów swobodnie
• Zmieniaj style używając Inspektora (kolory, czcionki, style linii)
• Dodawaj nowe elementy używając narzędzi Diagrammix
• Modyfikuj połączenia przeciągając punkty końcowe
• Stosuj automatyczny układ, aby reorganizować diagram

Wskazówka: Zdecyduj z góry, jak chcesz utrzymywać diagram. Używaj edytora źródła </>, aby utrzymywać go w notacji Mermaid, lub edytuj kształty bezpośrednio dla jednorazowego dopracowania wizualnego. Intensywne ręczne edycje mogą odbiegać od tego, co wygenerowałoby przerenderowanie źródła.

Ograniczenia

• Złożona stylizacja: Dyrektywy stylizacji Mermaid mogą nie przetłumaczyć się w pełni
• Podgrafy: Konwertowane do pogrupowanych kształtów
• Zaawansowane funkcje: Niektóre funkcje specyficzne dla Mermaid (jak obsługi kliknięć) są ignorowane
• Pełny obieg: Eksportowanie diagramu, który intensywnie edytowałeś ręcznie, może nie odtworzyć identycznej składni Mermaid — dla pełnych obiegów preferuj edytor źródła </>

Wskazówki

1. Oczyść po imporcie: Użyj automatycznego układu, aby uporządkować zaimportowane diagramy
2. Sprawdź relacje: Zweryfikuj, czy typy relacji zaimportowały się poprawnie
3. Stylizuj spójnie: Stosuj style Diagrammix dla dopracowanego wyglądu
4. Zachowaj źródło: Zapisuj oryginalne pliki Mermaid do kontroli wersji