Własne ikony SVG w Mermaid: zarejestruj swoją grafikę

Aby użyć własnej ikony SVG w Mermaid, umieść zawartość rysunku i wymiary jego układu współrzędnych w zestawie ikon Iconify, wywołaj mermaid.registerIconPacks() i odwołaj się do zarejestrowanej nazwy w diagramie. Sama nazwa pliku SVG nie rejestruje ikony.

Ten sposób pracy pasuje do strony lub aplikacji, w której kontrolujesz kod JavaScript Mermaid. Hostowany edytor Markdown może udostępniać tylko tekst diagramu, więc sprawdź dostępne opcje integracji, zanim przygotujesz całą kolekcję ikon. Zacznij od jednego prostego piktogramu i jednego łącznika. Zachowaj etykiety diagramu w Mermaid, aby pozostały oddzielone od grafiki.

Sprawdź, gdzie możesz zarejestrować pakiet

API rejestracji Mermaid przyjmuje zestaw ikon bezpośrednio lub funkcję ładującą, która go zwraca. Zarejestrowana wartość name staje się prefiksem używanym w diagramie. W tym przykładzie pakiet to garden, a jego ikona to leaf, co daje odwołanie garden:leaf.

Rejestracja powinna znajdować się w kodzie JavaScript przygotowującym mechanizm renderowania. Wklejenie tego kodu JavaScript do bloku kodu Mermaid nie wykonuje tej samej operacji. Jeśli Twoja platforma publikacyjna nie pozwala konfigurować mechanizmu renderowania, użyj obsługiwanych przez nią zestawów ikon albo wyrenderuj diagram w kontrolowanym przez siebie procesie i wstaw wyeksportowany wynik. Zachowaj kod źródłowy Mermaid obok tego wyniku na potrzeby późniejszych zmian.

Na potrzeby tego przewodnika użyj zwykłej strony HTML udostępnianej przez lokalny serwer HTTP. Ładuje ona moduł Mermaid w przypiętej wersji 12.0.0 z CDN, dlatego wymaga dostępu do sieci. Aplikacja produkcyjna może zamiast tego dołączyć wybraną wersję Mermaid do swojego pakietu. Zanim zastosujesz ten przykład, przetestuj tę wersję oraz politykę bezpieczeństwa treści swojego środowiska hostowania.

Zachowaj współrzędne rysunku SVG

Oto oryginalny liść użyty w naszym teście. Zapisz go jako leaf.svg, jeśli chcesz obejrzeć grafikę osobno:

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

Pole body w Iconify przechowuje zawartość wewnątrz elementu głównego SVG, bez zewnętrznego elementu <svg>. Prostokątny obszar układu współrzędnych jest przekazywany osobno jako left, top, width i height. W tym pliku początek układu współrzędnych znajduje się w punkcie zerowym, a wymiary wynoszą 32 na 24.

Nie kopiuj zamiast tego rozmiaru wyświetlania określonego w CSS. Plik wyświetlany w rozmiarze 64 pikseli nadal może mieć viewBox o wartości 0 0 32 24. Jego ścieżki zostały narysowane w tym drugim układzie współrzędnych. Jeśli początek układu jest różny od zera, zachowaj również odpowiadające mu wartości left i top albo przed spakowaniem świadomie przesuń grafikę na obszar roboczy z początkiem układu w punkcie zerowym.

Zestaw Iconify zawiera prefix oraz obiekt icons. Każdy klucz ikony nadaje nazwę jej rysunkowi. Jawne wymiary są tu przydatne: jeśli nie podaje ich ani ikona, ani zestaw, domyślne wartości szerokości i wysokości w Iconify wynoszą 16. Może to spowodować przycięcie grafiki narysowanej na większym obszarze roboczym.

Jeśli przygotowujesz rodzinę piktogramów, najpierw dopracuj ich obrys, odstępy od krawędzi i ciężar wizualny. Nasz przewodnik po przygotowaniu SVG do zestawu elementów interfejsu omawia te decyzje dotyczące grafiki źródłowej. Spakowanie ikony nie poprawia jej sylwetki.

Uruchom kompletny przykład z dwoma węzłami

Zapisz poniższy kod jako index.html w nowym folderze. Jeśli masz dostęp do Pythona, uruchom w tym folderze python3 -m http.server 8000, a następnie otwórz http://localhost:8000 w przeglądarce.

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

Powinien pojawić się liść obok symbolu bazy danych, z połączeniem biegnącym od Source do Library. Liść pochodzi z zarejestrowanego pakietu; database jest jedną z wbudowanych ikon architektury Mermaid. Dokumentacja składni diagramów architektury opisuje nazwy ikon w nawiasach okrągłych, etykiety w nawiasach kwadratowych oraz boki usług, do których podłącza się krawędzie.

Przykład wyłącza automatyczne renderowanie i wykonuje jedno jawne wywołanie render() po rejestracji. Dzięki temu podczas testowania kolejność pozostaje widoczna. Przy integracji z istniejącą witryną upewnij się, że rejestracja i wywołanie renderowania korzystają z tej samej instancji Mermaid.

To niewielki, zaufany rysunek stworzony na potrzeby przykładu. W przypadku dużej kolekcji ikon użyj narzędzi Iconify do importowania i oczyszczania, zamiast zakładać, że każdy wyeksportowany plik SVG można bez dodatkowej pracy sprowadzić do ciągu znaków ze ścieżkami. Czcionki, obrazy zewnętrzne, style i definicje, do których prowadzą odwołania, wymagają osobnej kontroli.

Porównaj brak rejestracji z brakiem wymiarów

Wyrenderowaliśmy trzy kopie tego diagramu w osobnych dokumentach przeglądarki, używając Mermaid 12.0.0. W pierwszej pominięto rejestrację. W drugiej zarejestrowano dwie ścieżki liścia, ale pominięto ich wymiary. W trzeciej zarejestrowano te same ścieżki z width: 32 i height: 24.

W pierwszym renderowaniu Mermaid wyświetlił znak zapytania w miejscu, w którym powinien pojawić się własny liść. Ścieżka liścia nie znalazła się w wyniku. W drugim wynik zawierał tę ścieżkę wewnątrz SVG z viewBox="0 0 16 16", a liść był wyraźnie przycięty. W trzecim ikona używała viewBox="0 0 32 24" i pojawił się kompletny liść.

Te obserwacje dotyczą tego przykładu testowego i tej wersji. Nie dowodzą, że każde środowisko hostowania sygnalizuje niedostępną ikonę w ten sam sposób. Przykład wykorzystuje też ręcznie napisane ścieżki SVG; nie jest wynikiem konwersji w PerfectVector.

Zachowaj działającą kopię minimalnego przykładu, zanim dodasz więcej ikon. Zmieniaj po jednej właściwości pakietu; w przeciwnym razie poprawka nazwy może ukryć osobny problem z wymiarami.

W razie potrzeby włącz grafikę rastrową do procesu

Jeśli Twój własny piktogram zachował się tylko jako PNG lub JPG, proces konwersji klipartu do SVG w PerfectVector może pomóc odzyskać edytowalne kontury. Przytnij kopię obrazu do piktogramu, obejrzyj podgląd wyniku wektoryzacji i sprawdź sylwetkę, wewnętrzne prześwity oraz niepożądane kształty tła. Następnie otwórz SVG w edytorze i przygotuj małą wersję, której zamierzasz używać w diagramie.

Zachowaj ten edytowalny plik źródłowy SVG. Spakuj zawartość rysunku i jego współrzędne dopiero wtedy, gdy będzie czytelny w docelowym rozmiarze ikony. Narysowanie prostego symbolu geometrycznego od nowa może być szybsze; fotografia może być czytelniejsza jako osobny obraz. Jeśli masz już odpowiednią grafikę SVG, zacznij od jej spakowania.

Wektoryzacja nie odzyskuje nazw usług diagramu, relacji ani kierunków łączników. Zachowaj je w kodzie źródłowym Mermaid. Jeśli korzystasz z edytora opartego na obszarze roboczym, w którym kształty zachowują się inaczej, zobacz własne kształty SVG w draw.io. W przypadku ikon wielokrotnego użytku na zwykłej stronie internetowej innym sposobem pakowania jest sprite symboli SVG. W przypadku diagramów opartych na DOT sprawdź przenoszenie obrazów SVG używanych w węzłach Graphviz, aby zobaczyć, czy własna grafika jest dołączana do wyeksportowanego grafu.

Zanim przekażesz diagram dalej, otwórz go ponownie w rzeczywistym procesie publikacji. Potwierdź, że ikona się ładuje, cała sylwetka mieści się w jej granicach, obie etykiety są czytelne, a łącznik wskazuje właściwy kierunek. Udane lokalne renderowanie to pierwszy etap kontroli, po którym następuje sprawdzenie w miejscu docelowym.

FAQ

Czy mogę umieścić nazwę pliku SVG w odwołaniu do ikony Mermaid? W procesie opartym na zarejestrowanym pakiecie ikon użyj nazwy pakietu i klucza ikony, na przykład garden:leaf. Przygotuj rysunek SVG jako dane ikony i zarejestruj ten pakiet w kodzie JavaScript mechanizmu renderowania.

Dlaczego moja własna ikona Mermaid jest przycięta? Porównaj źródłowy viewBox z właściwościami układu współrzędnych w danych ikony. Jeśli wymiarów nie podaje ani ikona, ani jej zestaw, domyślne wartości szerokości i wysokości wynoszą 16, co może być zbyt małym obszarem dla rysunku.

Czy to działa w każdym hostowanym edytorze Markdown? Nie. Platforma musi obsługiwać składnię diagramu i umożliwiać rejestrację wymaganego pakietu albo już go zawierać. Przetestuj rzeczywiste miejsce publikacji, zamiast zakładać, że ma taką samą konfigurację jak Twoje środowisko lokalne.

Źródła

1. Mermaid — Registering icon packs — Dokumentuje bezpośrednie przekazywanie danych ikon, funkcje ładujące i nazwy używane przy rejestracji.
2. Mermaid — Architecture diagrams — Definiuje ikony usług, natywne etykiety, wbudowane ikony i składnię krawędzi.
3. Iconify — IconifyIcon — Definiuje zawartość rysunku bez zewnętrznego elementu SVG oraz właściwości układu współrzędnych.
4. Iconify — IconifyJSON — Definiuje strukturę pakietu i domyślne wymiary dziedziczone przez ikony.

Masz piktogram do diagramu dostępny wyłącznie jako obraz rastrowy? Przygotuj wstępną wersję SVG w PerfectVector, sprawdź jej sylwetkę i prześwity, a następnie zarejestruj jedną ikonę i zweryfikuj jej granice oraz etykietę w docelowym mechanizmie renderowania Mermaid.