Mermaid özel SVG simgeleri: Çiziminizi kaydedin

Kendi SVG simgenizi Mermaid'de kullanmak için çizim içeriğini ve koordinat boyutlarını bir Iconify simge kümesine yerleştirin, mermaid.registerIconPacks() çağrısını yapın ve diyagramda kaydedilmiş ada başvurun. Tek başına bir SVG dosya adı, simgeyi kaydetmez.

Bu iş akışı, Mermaid JavaScript kodunu kontrol ettiğiniz bir sayfa veya uygulama için uygundur. Barındırılan bir Markdown düzenleyicisi yalnızca diyagram metnine erişim sunabilir; bu yüzden bütün bir simge koleksiyonu hazırlamadan önce entegrasyon seçeneklerini kontrol edin. Basit bir piktogram ve bir bağlantı çizgisiyle başlayın. Diyagramın etiketlerini Mermaid'de tutun; böylece çizimden ayrı kalırlar.

Paketi nerede kaydedebileceğinizi kontrol edin

Mermaid'in kayıt API'si, doğrudan bir simge kümesini veya böyle bir küme döndüren yükleyiciyi kabul eder. Kaydedilen name, diyagramınızda kullanılan önek olur. Bu örnekte paket garden, simgesi ise leaf olduğundan başvuru garden:leaf olur.

Kayıt işlemi, görüntüleme motorunu hazırlayan JavaScript kodunda yapılır. Bu JavaScript'i bir Mermaid kod bloğuna yapıştırmak aynı işlemi gerçekleştirmez. Yayın platformunuz görüntüleme motorunu yapılandırmanıza izin vermiyorsa desteklediği simge kümelerini kullanın veya diyagramı kontrol ettiğiniz bir iş akışında oluşturup dışa aktarılan sonucu ekleyin. Daha sonra düzenleyebilmek için Mermaid kaynağını bu sonuçla birlikte saklayın.

Bu uygulamalı anlatımda, yerel HTTP üzerinden sunulan standart bir HTML sayfası kullanın. Sayfa, sürümü sabitlenmiş Mermaid 12.0.0 modülünü bir CDN'den yükler; dolayısıyla ağ erişimi gerektirir. Üretim uygulaması bunun yerine seçtiği Mermaid sürümünü kendi paketine dahil edebilir. Örneği kullanmaya başlamadan önce o sürümü ve barındırma ortamınızın içerik güvenliği politikasını test edin.

SVG'nin çizim koordinatlarını koruyun

Testimizde kullanılan özgün yaprak aşağıdadır. Çizimi ayrı incelemek isterseniz leaf.svg olarak kaydedin:

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

Iconify'ın body alanı, dıştaki <svg> öğesi hariç SVG kökünün içindeki içeriği tutar. Koordinat dikdörtgeni ayrı olarak left, top, width ve height değerleriyle taşınır. Bu dosyada başlangıç noktası sıfır, boyutlar ise 32 × 24'tür.

Bunun yerine ekranda kullanılan CSS boyutunu kopyalamayın. 64 piksel boyutunda gösterilen bir dosyanın viewBox değeri yine de 0 0 32 24 olabilir. Yolları bu ikinci koordinat sisteminde çizilmiştir. Başlangıç noktası sıfır değilse ilgili left ve top değerlerini de koruyun veya çizimi paketlemeden önce bilinçli olarak başlangıç noktası sıfır olan bir tuvale taşıyın.

Bir Iconify kümesi, prefix ve icons nesnesi içerir. Her simge anahtarı, kendi çizimini adlandırır. Burada boyutları açıkça belirtmek faydalıdır: ne simge ne de küme bunları sağlıyorsa Iconify'ın varsayılan genişlik ve yüksekliği 16'dır. Bu, daha büyük bir tuval için çizilen içeriğin kırpılmasına neden olabilir.

Bir piktogram ailesi hazırlıyorsanız önce dış konturlarını, kenar boşluklarını ve görsel ağırlıklarını tamamlayın. SVG arayüz kiti hazırlama rehberimiz, kaynak çizime ilişkin bu kararları ele alır. Bir simgeyi paketlemek, siluetini iyileştirmez.

İki düğümlü eksiksiz bir örnek çalıştırın

Aşağıdaki içeriği yeni bir klasörde index.html olarak kaydedin. Python mevcutsa o klasörde python3 -m http.server 8000 komutunu çalıştırın, ardından tarayıcınızda http://localhost:8000 adresini açın.

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

Bir veritabanı simgesinin yanında, Source'tan Library'ye bağlanan yaprağı görmelisiniz. Yaprak kaydedilen paketten gelir; database, Mermaid'in yerleşik mimari simgelerinden biridir. Mimari sözdizimi referansı, parantez içindeki simge adlarını, köşeli parantez içindeki etiketleri ve bağlantılar için kullanılan servis kenarlarını açıklar.

Örnek, otomatik görüntülemeyi kapatır ve kayıt işleminden sonra açıkça tek bir render() çağrısı yapar. Böylece test sırasında işlem sırası görünür kalır. Mevcut bir siteye entegre ederken kayıt işleminin ve görüntüleme çağrısının aynı Mermaid örneğini kullandığından emin olun.

Bu, örnek için hazırlanmış küçük ve güvenilir bir çizimdir. Büyük bir simge koleksiyonu için, dışa aktarılan her SVG'nin ek işlem olmadan bir yol dizgesine indirgenebileceğini varsaymak yerine Iconify'ın içe aktarma ve temizleme araçlarını kullanın. Yazı tipleri, haricî görüntüler, stiller ve başvurulan tanımlar ayrıca incelenmelidir.

Eksik kaydı ve eksik boyutları karşılaştırın

Mermaid 12.0.0 kullanarak bu diyagramın üç kopyasını ayrı tarayıcı belgelerinde görüntüledik. İlkinde kayıt işlemi yapılmadı. İkincisinde iki yaprak yolu kaydedildi, ancak boyutları belirtilmedi. Üçüncüsünde aynı yollar width: 32 ve height: 24 ile kaydedildi.

İlk görüntülemede Mermaid, özel yaprağın görünmesi gereken yerde bir soru işareti gösterdi. Yaprak yolu çıktıda yoktu. İkincisinde çıktı, bu yolu viewBox="0 0 16 16" olan bir SVG içinde içeriyordu ve yaprak belirgin şekilde kırpılmıştı. Üçüncüsünde simge viewBox="0 0 32 24" kullanıyordu ve yaprağın tamamı görünüyordu.

Bu gözlemler, bu test örneğini ve sürümü tanımlar. Her barındırma ortamının kullanılamayan bir simgeyi aynı şekilde bildirdiğini göstermez. Örnekte ayrıca elle yazılmış SVG yolları kullanılır; bu bir PerfectVector dönüştürme sonucu değildir.

Daha fazla simge eklemeden önce en küçük örneğin çalışan bir kopyasını saklayın. Her seferinde yalnızca bir paket özelliğini değiştirin; aksi hâlde bir adlandırma düzeltmesi, ayrı bir boyutlandırma sorununu gizleyebilir.

Gerektiğinde raster çizimi iş akışına dahil edin

Özel piktogramınız yalnızca PNG veya JPG olarak kalmışsa PerfectVector'ın illüstrasyondan SVG'ye dönüştürme iş akışı, düzenlenebilir konturları geri kazanmanıza yardımcı olabilir. Bir kopyayı piktogramı kapsayacak şekilde kırpın, vektör sonucunu önizleyin ve silueti, iç boşlukları ve istenmeyen arka plan şekillerini inceleyin. Ardından SVG'yi bir düzenleyicide açın ve diyagramda kullanmayı düşündüğünüz küçük sürümü hazırlayın.

Bu düzenlenebilir SVG aslını saklayın. Çizim içeriğini ve koordinatlarını ancak amaçlanan simge boyutunda açıkça anlaşılır olduktan sonra paketleyin. Basit bir geometrik simgeyi yeniden çizmek daha hızlı olabilir; bir fotoğrafı ise ayrı görüntü olarak kullanmak daha anlaşılır olabilir. Zaten uygun SVG çiziminiz varsa paketleme adımından başlayın.

Vektörleştirme, diyagramın servis adlarını, ilişkilerini veya bağlantı yönlerini geri kazanmaz. Bunları Mermaid kaynağında tutun. Şekillerin farklı davrandığı, tuval tabanlı bir düzenleyici için draw.io'da özel SVG şekilleri yazısına bakın. Standart bir web sayfasında yeniden kullanılabilir simgeler için SVG simge sprite'ı başka bir paketleme yoludur. DOT tabanlı diyagramlarda, özel çizimin dışa aktarılan grafikle birlikte taşınıp taşınmadığını görmek için Graphviz SVG düğüm görüntülerinin teslimi yazısını inceleyin.

Diyagramınızı teslim etmeden önce gerçek yayın iş akışı üzerinden yeniden açın. Simgenin yüklendiğini, siluetin tamamının sığdığını, her iki etiketin okunabildiğini ve bağlantının doğru yönü gösterdiğini doğrulayın. Başarılı bir yerel görüntüleme ilk kontrolünüzdür; ardından hedef ortamda kontrol yapmanız gerekir.

Sık sorulan sorular

Bir Mermaid simge başvurusuna SVG dosya adı yazabilir miyim? Kaydedilmiş simge paketi iş akışında garden:leaf gibi bir paket adı ve simge anahtarı kullanın. SVG çizimini simge verisi olarak hazırlayın ve bu paketi görüntüleme motorunun JavaScript kodunda kaydedin.

Özel Mermaid simgem neden kırpılıyor? Kaynak viewBox değerini simge verisinin koordinat özellikleriyle karşılaştırın. Hem simgede hem de kümesinde boyutlar eksikse varsayılan genişlik ve yükseklik 16 olur; bu değer çizim için fazla küçük olabilir.

Bu yöntem barındırılan tüm Markdown düzenleyicilerinde çalışır mı? Hayır. Barındırma ortamı diyagram sözdizimini desteklemeli ve gereken paketi kaydetmenin bir yolunu sunmalı ya da paketi zaten içermelidir. Yerel kurulumunuzla aynı olduğunu varsaymak yerine gerçek yayın hedefini test edin.

Kaynaklar

1. Mermaid — Registering icon packs — Doğrudan simge verisini, yükleyicileri ve kayıt adlarını belgeler.
2. Mermaid — Architecture diagrams — Servis simgelerini, diyagramın kendi etiketlerini, yerleşik simgeleri ve bağlantı sözdizimini tanımlar.
3. Iconify — IconifyIcon — SVG sarmalayıcısı olmadan çizim içeriğini ve koordinat özelliklerini tanımlar.
4. Iconify — IconifyJSON — Paket yapısını ve simgelerin devraldığı varsayılan boyutları tanımlar.

Diyagramınız için yalnızca raster biçiminde bir piktogramınız mı var? PerfectVector ile bir SVG adayı hazırlayın, siluetini ve boşluklarını inceleyin; ardından tek bir simgeyi kaydedip nihai Mermaid görüntüleme motorunuzda sınırlarını ve etiketini doğrulayın.