Supporto Mermaid

Diagrammix3 supporta l'importazione e l'esportazione di diagrammi usando la sintassi Mermaid, un popolare linguaggio di diagrammazione basato su testo.

Cos'è Mermaid?

Mermaid è uno strumento di diagrammazione basato su JavaScript che utilizza una sintassi simile a Markdown per definire i diagrammi. È comunemente usato nella documentazione, nei wiki e nei file README.

Esempio di sintassi Mermaid:

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

Importare Diagrammi Mermaid

Nota: L'importazione e l'esportazione Mermaid sono una funzionalità PRO.

Inserisci Mermaid (con anteprima e convalida)

Il modo più rapido per portare Mermaid sulla tua tela è il pannello Inserisci Mermaid, che visualizza l'anteprima e convalida il diagramma prima che venga posizionato qualcosa.

1. Vai su Modifica → Inserisci Mermaid
2. Incolla o digita la sintassi Mermaid nell'editor
3. Mentre digiti, Diagrammix convalida la sintassi in tempo reale e mostra:
   • se il diagramma è valido
   • il tipo di diagramma rilevato
   • il numero di nodi e connettori
   
   Gli errori vengono evidenziati in linea, così puoi correggerli prima che tocchino la tela.
4. Fai clic su Applica per posizionare il diagramma, oppure Annulla per chiudere

Incollare Mermaid dagli appunti passa attraverso la stessa convalida, così la sintassi non valida non produce mai un diagramma rotto.

Nota: Mermaid si importa incollando o digitando nel pannello Inserisci Mermaid — non esiste un comando separato per "importare un file". Per portare un file .mmd, aprilo in un qualsiasi editor di testo e incollane il contenuto.

Tipi di Diagrammi Supportati

Diagrammix riconosce un'ampia gamma di tipi di diagrammi Mermaid, tra cui:

Altri tipi Mermaid (cronologia, user journey, quadrante, grafico XY, Sankey, grafico Git e altri ancora) vengono riconosciuti e importati, ma sono resi come un grafico generico di nodi e connettori anziché come un layout specializzato. Il pannello Inserisci Mermaid ti indica il tipo rilevato prima che tu applichi.

Sintassi dei Diagrammi a Stati

I diagrammi a stati modellano gli stati in cui un oggetto può trovarsi e le transizioni tra gli stati.

Diagramma a stati di base:

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

Stati e transizioni:

• [*] rappresenta gli stati iniziali e finali
• --> crea una freccia di transizione
• : etichetta aggiunge etichette alle transizioni
• Gli stati annidati usano l'indentazione

Stati compositi:

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

Risultato: Un diagramma a macchina a stati con le forme degli stati corrette e le transizioni etichettate.

Esempi di Importazione

Diagramma di Flusso

Input Mermaid:

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

Risultato: Un diagramma di flusso dall'alto verso il basso con rettangoli, rettangoli arrotondati e rombi collegati da frecce etichettate.

Diagramma di Sequenza

Input Mermaid:

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

Risultato: Un diagramma di sequenza con due partecipanti e frecce di messaggio.

Diagramma delle Classi

Input Mermaid:

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

Risultato: Un diagramma delle classi UML con relazioni di ereditarietà.

Esportare in Mermaid

Copia Mermaid

Diagrammix esporta in Mermaid tramite gli appunti — non esiste un comando separato per "esportare su file".

1. Seleziona le forme che vuoi esportare, oppure non selezionare nulla per esportare l'intera tela
2. Vai su Modifica → Copia Mermaid
3. Incolla la sintassi Mermaid dove ne hai bisogno (poi salvala come file .mmd se vuoi)

L'esportazione si adatta a ciò che rientra nell'ambito: una mappa mentale viene copiata come sintassi mindmap e una pagina di classi o di sequenza UML come classDiagram / sequenceDiagram; qualsiasi altra cosa viene esportata come flowchart.

Continua a Modificare in Mermaid (Andata-Ritorno)

I diagrammi Mermaid importati mantengono il loro sorgente, così puoi continuare a lavorare nella notazione Mermaid invece di modificare le forme una per una.

1. Seleziona un diagramma Mermaid importato
2. Fai clic sul pulsante </> (Modifica Sorgente Mermaid) sul diagramma
3. Il pannello Modifica Sorgente Mermaid si apre con il testo Mermaid originale già inserito
4. Modifica il testo e ridisegna per aggiornare il diagramma in posizione

Se le tue modifiche cambiano la struttura del diagramma (ad esempio, rimuovendo nodi da cui dipendono altri elementi), il pannello elenca quelle incompatibilità in anticipo così puoi decidere prima di confermare.

Modifica come Oggetti Nativi

Puoi anche modificare un diagramma importato direttamente come oggetti nativi di Diagrammix:

• Sposta e ridimensiona le forme liberamente
• Cambia gli stili usando l'Inspector (colori, font, stili di linea)
• Aggiungi nuovi elementi usando gli strumenti di Diagrammix
• Modifica le connessioni trascinando gli endpoint
• Applica il layout automatico per riorganizzare il diagramma

Suggerimento: Decidi in anticipo come vuoi mantenere un diagramma. Usa l'editor sorgente </> per tenerlo guidato da Mermaid, oppure modifica le forme direttamente per una rifinitura visiva una tantum. Le modifiche manuali pesanti possono divergere da ciò che produrrebbe il ridisegno del sorgente.

Limitazioni

• Stili complessi: Le direttive di stile Mermaid potrebbero non tradursi completamente
• Sottografi: Convertiti in forme raggruppate
• Funzionalità avanzate: Alcune funzionalità specifiche di Mermaid (come i gestori di clic) vengono ignorate
• Andata-ritorno: L'esportazione di un diagramma che hai modificato pesantemente a mano potrebbe non riprodurre una sintassi Mermaid identica — per gli andata-ritorno, preferisci l'editor sorgente </>

Suggerimenti

1. Fai pulizia dopo l'importazione: Usa il layout automatico per organizzare i diagrammi importati
2. Verifica le relazioni: Controlla che i tipi di relazione siano stati importati correttamente
3. Stile coerente: Applica gli stili di Diagrammix per un aspetto curato
4. Conserva il sorgente: Salva i tuoi file Mermaid originali per il controllo versione