Eigene SVG-Icons in Mermaid: Deine Grafik registrieren

Um dein eigenes SVG-Icon in Mermaid zu verwenden, lege seinen Zeicheninhalt und seine Koordinatenabmessungen in einem Iconify-Icon-Set ab, rufe mermaid.registerIconPacks() auf und referenziere den registrierten Namen im Diagramm. Ein SVG-Dateiname allein registriert kein Icon.

Dieser Ablauf eignet sich für eine Seite oder Anwendung, auf der du das Mermaid-JavaScript kontrollierst. Ein gehosteter Markdown-Editor kann dir nur den Diagrammtext zugänglich machen. Prüfe deshalb seine Integrationsmöglichkeiten, bevor du eine ganze Icon-Sammlung vorbereitest. Beginne mit einem einfachen Piktogramm und einem Verbinder. Behalte die Diagrammbeschriftungen in Mermaid, damit sie von der Grafik getrennt bleiben.

Prüfen, wo du das Paket registrieren kannst

Mermaids Registrierungs-API akzeptiert ein Icon-Set direkt oder eine Ladefunktion, die eines zurückgibt. Der registrierte name wird zum Präfix, das du im Diagramm verwendest. In diesem Beispiel heißt das Paket garden und sein Icon leaf, woraus die Referenz garden:leaf entsteht.

Die Registrierung gehört in das JavaScript, das den Renderer vorbereitet. Dieses JavaScript in einen Mermaid-Codeblock einzufügen ist nicht dieselbe Operation. Wenn deine Veröffentlichungsplattform keine Konfiguration ihres Renderers erlaubt, verwende ihre unterstützten Icon-Sets oder rendere das Diagramm in einem von dir kontrollierten Ablauf und füge das exportierte Ergebnis ein. Behalte die Mermaid-Quelle neben diesem Ergebnis für spätere Änderungen.

Verwende für diese Anleitung eine gewöhnliche HTML-Seite, die über lokales HTTP bereitgestellt wird. Sie lädt ein auf Version 12.0.0 festgelegtes Mermaid-Modul von einem CDN und benötigt deshalb Netzwerkzugriff. Eine Produktionsanwendung kann ihre gewählte Mermaid-Version stattdessen bündeln. Teste diese Version und die Content Security Policy deines Hosts, bevor du das Beispiel übernimmst.

Die Zeichenkoordinaten des SVG erhalten

Hier ist das eigene Blatt aus unserem Test. Speichere es als leaf.svg, wenn du die Grafik separat prüfen möchtest:

<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>

Iconifys Feld body enthält den Inhalt innerhalb des SVG-Wurzelelements, ohne dieses äußere <svg>-Element. Das Koordinatenrechteck wird separat als left, top, width und height übergeben. Bei dieser Datei liegt der Ursprung bei null, und die Abmessungen sind 32 mal 24.

Kopiere nicht stattdessen die gerenderte CSS-Größe. Eine mit 64 Pixeln angezeigte Datei kann weiterhin eine viewBox von 0 0 32 24 haben. Ihre Pfade wurden in diesem letzteren Koordinatensystem gezeichnet. Bei einem Ursprung ungleich null behalte auch die entsprechenden Werte für left und top bei oder verschiebe die Grafik vor dem Verpacken bewusst auf eine Zeichenfläche mit Nullursprung.

Ein Iconify-Set enthält ein prefix und ein icons-Objekt. Jeder Icon-Schlüssel benennt seine Zeichnung. Ausdrückliche Abmessungen sind hier hilfreich: Wenn weder das Icon noch das Set sie angibt, verwendet Iconify für Breite und Höhe den Standardwert 16. Das kann eine für eine größere Zeichenfläche gezeichnete Grafik abschneiden.

Wenn du eine Familie von Piktogrammen vorbereitest, stelle zuerst Kontur, Randabstand und visuelles Gewicht fertig. Unser Leitfaden zur Vorbereitung eines SVG-UI-Kits behandelt diese Entscheidungen zur Quellgrafik. Das Verpacken eines Icons verbessert seine Silhouette nicht.

Ein vollständiges Beispiel mit zwei Knoten ausführen

Speichere Folgendes als index.html in einem neuen Ordner. Wenn Python verfügbar ist, führe dort python3 -m http.server 8000 aus und öffne dann http://localhost:8000 in deinem 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>

Du solltest das Blatt neben einem Datenbanksymbol sehen, verbunden von Source zu Library. Das Blatt stammt aus dem registrierten Paket; database ist eines der eingebauten Architektur-Icons von Mermaid. Die Referenz zur Architektursyntax beschreibt Icon-Namen in runden Klammern, Beschriftungen in eckigen Klammern und die für Kanten verwendeten Seiten der Dienste.

Das Beispiel deaktiviert automatisches Rendern und ruft nach der Registrierung einmal ausdrücklich render() auf. Dadurch bleibt die Reihenfolge beim Testen sichtbar. Stelle bei der Integration in eine vorhandene Website sicher, dass Registrierung und Renderaufruf dieselbe Mermaid-Instanz verwenden.

Das ist eine kleine, vertrauenswürdige Zeichnung, die für das Beispiel erstellt wurde. Verwende für eine große Icon-Sammlung Iconifys Import- und Bereinigungswerkzeuge, statt anzunehmen, dass jedes exportierte SVG ohne weitere Arbeit auf eine Pfadzeichenfolge reduziert werden kann. Schriften, externe Bilder, Stile und referenzierte Definitionen verdienen eine eigene Prüfung.

Fehlende Registrierung und fehlende Abmessungen vergleichen

Wir haben drei Kopien dieses Diagramms in separaten Browserdokumenten mit Mermaid 12.0.0 gerendert. Die erste ließ die Registrierung weg. Die zweite registrierte die zwei Blattpfade, ließ aber ihre Abmessungen weg. Die dritte registrierte dieselben Pfade mit width: 32 und height: 24.

In der ersten Darstellung zeigte Mermaid anstelle des eigenen Blatts ein Fragezeichen. Der Blattpfad fehlte in der Ausgabe. In der zweiten enthielt die Ausgabe diesen Pfad innerhalb eines SVG mit viewBox="0 0 16 16", und das Blatt war sichtbar abgeschnitten. In der dritten verwendete das Icon viewBox="0 0 32 24", und das vollständige Blatt erschien.

Diese Beobachtungen beschreiben dieses Testbeispiel und diese Version. Sie belegen nicht, dass jeder Host ein nicht verfügbares Icon auf dieselbe Weise meldet. Das Beispiel verwendet außerdem von Hand geschriebene SVG-Pfade; es ist kein PerfectVector-Konvertierungsergebnis.

Behalte eine funktionierende Kopie des Minimalbeispiels, bevor du weitere Icons hinzufügst. Ändere jeweils nur eine Paketeigenschaft; andernfalls kann eine Namenskorrektur ein separates Größenproblem verdecken.

Bei Bedarf Rastergrafik in den Ablauf einbringen

Wenn dein eigenes Piktogramm nur als PNG oder JPG erhalten ist, kann PerfectVectors Clipart-zu-SVG-Ablauf helfen, bearbeitbare Konturen zu rekonstruieren. Schneide eine Kopie auf das Piktogramm zu, sieh dir das Vektorergebnis an und prüfe Silhouette, innere Zwischenräume und unerwünschte Hintergrundformen. Öffne das SVG anschließend in einem Editor und bereite die kleine Version vor, die du im Diagramm verwenden willst.

Behalte diese bearbeitbare SVG-Vorlage. Verpacke ihren Zeicheninhalt und ihre Koordinaten erst, wenn sie in der vorgesehenen Icon-Größe klar erkennbar ist. Ein einfaches geometrisches Symbol lässt sich möglicherweise schneller neu zeichnen; ein Foto kann als separates Bild klarer sein. Wenn du bereits geeignete SVG-Grafik hast, beginne mit dem Verpackungsschritt.

Die Vektorisierung rekonstruiert weder Dienstnamen noch Beziehungen noch Verbinderrichtungen des Diagramms. Behalte diese in der Mermaid-Quelle. Für einen Editor mit Zeichenfläche und anderem Formverhalten lies eigene SVG-Formen in draw.io. Für wiederverwendbare Icons auf einer gewöhnlichen Webseite ist ein SVG-Symbol-Sprite ein anderer Verpackungsweg. Für DOT-basierte Diagramme prüfe die Auslieferung von SVG-Knotenbildern in Graphviz, um festzustellen, ob eigene Grafik mit dem exportierten Graphen mitgeliefert wird.

Öffne dein Diagramm vor der Übergabe erneut über den tatsächlichen Veröffentlichungsablauf. Bestätige, dass das Icon lädt, die vollständige Silhouette hineinpasst, beide Beschriftungen lesbar sind und der Verbinder in die richtige Richtung zeigt. Eine erfolgreiche lokale Darstellung ist deine erste Prüfung, gefolgt von einer Prüfung am Zielort.

FAQ

Kann ich einen SVG-Dateinamen in eine Mermaid-Icon-Referenz schreiben? Verwende beim Ablauf mit registrierten Icon-Paketen einen Paketnamen und einen Icon-Schlüssel wie garden:leaf. Bereite die SVG-Zeichnung als Icon-Daten vor und registriere dieses Paket im JavaScript des Renderers.

Warum wird mein eigenes Mermaid-Icon abgeschnitten? Vergleiche die Quell-viewBox mit den Koordinateneigenschaften der Icon-Daten. Fehlen Abmessungen sowohl im Icon als auch in seinem Set, sind Breite und Höhe standardmäßig 16, was für die Zeichnung zu klein sein kann.

Funktioniert das in jedem gehosteten Markdown-Editor? Nein. Der Host muss die Diagrammsyntax unterstützen und eine Möglichkeit bieten, das erforderliche Paket zu registrieren, oder es bereits enthalten. Teste den tatsächlichen Veröffentlichungsort, statt anzunehmen, dass er dieselbe Einrichtung wie deine lokale Umgebung hat.

Quellen

1. Mermaid — Icon-Pakete registrieren — Dokumentiert direkte Icon-Daten, Ladefunktionen und Registrierungsnamen.
2. Mermaid — Architekturdiagramme — Definiert Dienst-Icons, native Beschriftungen, eingebaute Icons und Kantensyntax.
3. Iconify — IconifyIcon — Definiert Zeicheninhalt ohne SVG-Hülle und Koordinateneigenschaften.
4. Iconify — IconifyJSON — Definiert Paketstruktur und die von Icons übernommenen Standardabmessungen.

Du hast ein Piktogramm für dein Diagramm nur als Rasterbild? Erstelle einen SVG-Kandidaten mit PerfectVector, prüfe seine Silhouette und Zwischenräume, registriere dann ein Icon und überprüfe seine Begrenzungen und Beschriftung in deinem endgültigen Mermaid-Renderer.