Icone SVG Mermaid: registra la tua grafica

Per usare una tua icona SVG in Mermaid, inserisci il contenuto del disegno e le dimensioni del suo sistema di coordinate in un insieme di icone Iconify, chiama mermaid.registerIconPacks() e fai riferimento al nome registrato nel diagramma. Il solo nome di un file SVG non registra un'icona.

Questa procedura è adatta a una pagina o applicazione in cui controlli il JavaScript di Mermaid. Un editor Markdown ospitato potrebbe esporre soltanto il testo del diagramma, quindi controlla le opzioni di integrazione prima di preparare un'intera raccolta di icone. Inizia con un pittogramma semplice e un connettore. Mantieni le etichette del diagramma in Mermaid, così rimangono separate dalla grafica.

Controlla dove puoi registrare il pacchetto

L'API di registrazione di Mermaid accetta direttamente un insieme di icone oppure un caricatore che ne restituisce uno. Il name registrato diventa il prefisso usato nel diagramma. In questo esempio, il pacchetto è garden e la sua icona è leaf, producendo il riferimento garden:leaf.

La registrazione va nel JavaScript che prepara il renderer. Incollare quel JavaScript in un blocco di codice Mermaid non è la stessa operazione. Se la piattaforma di pubblicazione non permette di configurare il renderer, usa gli insiemi di icone supportati oppure renderizza il diagramma in una procedura che controlli e inserisci il risultato esportato. Conserva il sorgente Mermaid insieme a quel risultato per le modifiche successive.

Per questa guida pratica, usa una normale pagina HTML servita tramite HTTP locale. Carica da una CDN il modulo Mermaid nella versione fissata 12.0.0 e richiede quindi accesso alla rete. Un'applicazione di produzione può invece includere nel proprio pacchetto la versione Mermaid scelta. Verifica quella versione e la politica di sicurezza dei contenuti dell'ambiente di destinazione prima di adottare l'esempio.

Conserva le coordinate del disegno SVG

Ecco la foglia originale usata nella nostra prova. Salvala come leaf.svg se vuoi ispezionare la grafica separatamente:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 24">
  <path fill="#167c72"
    d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>
  <path fill="none" stroke="#d7f1ca" stroke-width="1.8"
    d="M5 18L23 7"/>
</svg>

Il campo body di Iconify contiene il contenuto all'interno della radice SVG, senza l'elemento esterno <svg>. Il rettangolo di coordinate viene trasmesso separatamente come left, top, width e height. Per questo file, l'origine è zero e le dimensioni sono 32 per 24.

Non copiare invece le dimensioni CSS renderizzate. Un file visualizzato a 64 pixel può comunque avere un viewBox di 0 0 32 24. I suoi tracciati sono stati disegnati in quest'ultimo sistema di coordinate. Per un'origine diversa da zero, conserva anche i valori left e top corrispondenti oppure trasla deliberatamente la grafica su una tela con origine zero prima di preparare il pacchetto.

Un insieme Iconify contiene un prefix e un oggetto icons. Ogni chiave di icona dà un nome al suo disegno. Le dimensioni esplicite sono utili qui: se non le forniscono né l'icona né l'insieme, larghezza e altezza predefinite di Iconify sono 16. Questo può ritagliare grafica disegnata per una tela più grande.

Se stai preparando una famiglia di pittogrammi, completa prima contorno, margini e peso visivo. La nostra guida alla preparazione di SVG per kit UI tratta queste decisioni sulla grafica sorgente. Preparare un'icona come pacchetto non ne migliora la sagoma.

Esegui un esempio completo con due nodi

Salva il codice seguente come index.html in una nuova cartella. Se Python è disponibile, esegui python3 -m http.server 8000 in quella cartella, poi apri http://localhost:8000 nel browser.

<!doctype html>
<meta charset="utf-8">
<title>Custom Mermaid leaf icon</title>
<div id="diagram"></div>
 
<script type="module">
import mermaid from
  'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
 
const icons = {
  prefix: 'garden',
  icons: {
    leaf: {
      width: 32,
      height: 24,
      body: '<path fill="#167c72" d="M3 19C1 5 14 2 29 3C29 17 17 25 3 19Z"/>' +
        '<path fill="none" stroke="#d7f1ca" stroke-width="1.8" d="M5 18L23 7"/>'
    }
  }
};
 
mermaid.registerIconPacks([{ name: 'garden', icons }]);
mermaid.initialize({ startOnLoad: false, theme: 'neutral' });
 
const definition = `architecture-beta
  service source(garden:leaf)[Source]
  service library(database)[Library]
  source:R --> L:library`;
 
const { svg } = await mermaid.render('garden-diagram', definition);
document.querySelector('#diagram').innerHTML = svg;
</script>

Dovresti vedere la foglia accanto a un simbolo di database, collegata da Source a Library. La foglia proviene dal pacchetto registrato; database è una delle icone di architettura integrate in Mermaid. Il riferimento alla sintassi dell'architettura descrive i nomi delle icone tra parentesi tonde, le etichette tra parentesi quadre e i lati dei servizi usati per gli archi.

L'esempio disattiva il rendering automatico ed esegue una chiamata esplicita render() dopo la registrazione. Questo rende visibile l'ordine durante le prove. Quando lo integri in un sito esistente, assicurati che registrazione e chiamata di rendering usino la stessa istanza di Mermaid.

Questo è un disegno piccolo e attendibile, creato per l'esempio. Per una raccolta ampia di icone, usa gli strumenti di importazione e pulizia di Iconify invece di presumere che ogni SVG esportato possa essere ridotto a una stringa di tracciato senza ulteriore lavoro. Caratteri, immagini esterne, stili e definizioni referenziate meritano un'ispezione separata.

Confronta registrazione mancante e dimensioni mancanti

Abbiamo renderizzato tre copie di questo diagramma in documenti separati del browser usando Mermaid 12.0.0. La prima ometteva la registrazione. La seconda registrava i due tracciati della foglia ma ne ometteva le dimensioni. La terza registrava gli stessi tracciati con width: 32 e height: 24.

Nel primo rendering, Mermaid mostrava un punto interrogativo nel punto in cui avrebbe dovuto apparire la foglia personalizzata. Il tracciato della foglia era assente dall'output. Nel secondo, l'output conteneva quel tracciato all'interno di un SVG con viewBox="0 0 16 16", e la foglia era visibilmente ritagliata. Nel terzo, l'icona usava viewBox="0 0 32 24" e appariva la foglia completa.

Queste osservazioni descrivono questo esempio e questa versione. Non dimostrano che ogni ambiente segnali allo stesso modo un'icona non disponibile. L'esempio usa inoltre tracciati SVG scritti a mano; non è un risultato di conversione PerfectVector.

Conserva una copia funzionante dell'esempio minimo prima di aggiungere altre icone. Cambia una proprietà del pacchetto alla volta; altrimenti una correzione del nome può nascondere un problema separato di dimensioni.

Inserisci grafica raster nella procedura quando serve

Se il pittogramma personalizzato esiste ormai soltanto come PNG o JPG, la procedura di PerfectVector da clipart a SVG può aiutarti a recuperare contorni modificabili. Ritaglia una copia sul pittogramma, visualizza l'anteprima del risultato vettoriale e ispeziona sagoma, spazi interni e forme indesiderate di sfondo. Apri poi l'SVG in un editor e prepara la versione piccola che intendi usare nel diagramma.

Conserva quell'originale SVG modificabile. Prepara il pacchetto con contenuto del disegno e coordinate soltanto quando la grafica è chiaramente leggibile alle dimensioni previste per l'icona. Un simbolo geometrico semplice potrebbe essere più rapido da ridisegnare; una fotografia potrebbe essere più chiara come immagine separata. Se possiedi già una grafica SVG adatta, inizia dal passaggio di preparazione del pacchetto.

La vettorializzazione non recupera nomi dei servizi, relazioni o direzioni dei connettori del diagramma. Mantienili nel sorgente Mermaid. Per un editor con tela e comportamenti diversi delle forme, leggi le forme SVG personalizzate in draw.io. Per icone riutilizzabili in una normale pagina web, uno sprite di simboli SVG è un altro metodo di preparazione. Per i diagrammi basati su DOT, consulta la distribuzione delle immagini SVG dei nodi Graphviz per vedere se la grafica personalizzata accompagna il grafo esportato.

Prima di consegnare il diagramma, riaprilo attraverso la procedura effettiva di pubblicazione. Conferma che l'icona si carichi, che la sagoma completa rientri nello spazio, che entrambe le etichette siano leggibili e che il connettore punti nella direzione giusta. Un rendering locale riuscito è il controllo iniziale, seguito dal controllo della destinazione.

FAQ

Posso inserire il nome di un file SVG in un riferimento di icona Mermaid? Per la procedura con pacchetto di icone registrato, usa un nome del pacchetto e una chiave dell'icona come garden:leaf. Prepara il disegno SVG come dati dell'icona e registra quel pacchetto nel JavaScript del renderer.

Perché la mia icona Mermaid personalizzata è ritagliata? Confronta il viewBox sorgente con le proprietà di coordinate dei dati dell'icona. Se mancano le dimensioni sia nell'icona sia nel suo insieme, larghezza e altezza predefinite sono 16, e potrebbero essere troppo piccole per il disegno.

Funziona in ogni editor Markdown ospitato? No. L'ambiente deve supportare la sintassi del diagramma e offrire un modo per registrare il pacchetto richiesto oppure includerlo già. Prova la destinazione effettiva di pubblicazione invece di presumere che condivida la configurazione locale.

Fonti

1. Mermaid — Registrazione dei pacchetti di icone — Documenta dati delle icone diretti, caricatori e nomi di registrazione.
2. Mermaid — Diagrammi di architettura — Definisce icone dei servizi, etichette native, icone integrate e sintassi degli archi.
3. Iconify — IconifyIcon — Definisce il contenuto del disegno senza il contenitore SVG e le proprietà di coordinate.
4. Iconify — IconifyJSON — Definisce la struttura dei pacchetti e le dimensioni predefinite ereditate dalle icone.

Hai un pittogramma solo raster per il diagramma? Prepara un candidato SVG con PerfectVector, ispeziona sagoma e spazi interni, poi registra un'icona e verificane limiti ed etichetta nel renderer Mermaid finale.