Ikon SVG Khusus Mermaid: Daftarkan Karya Anda

Untuk memakai ikon SVG Anda sendiri dalam Mermaid, masukkan isi gambar dan dimensi koordinatnya ke set ikon Iconify, panggil mermaid.registerIconPacks(), lalu rujuk nama yang terdaftar dalam diagram. Nama file SVG saja tidak mendaftarkan ikon.

Alur ini sesuai untuk halaman atau aplikasi tempat Anda mengendalikan JavaScript Mermaid. Editor Markdown yang dihosting mungkin hanya menyediakan teks diagram, jadi periksa opsi integrasinya sebelum menyiapkan seluruh koleksi ikon. Mulai dengan satu piktogram sederhana dan satu konektor. Simpan label diagram dalam Mermaid agar tetap terpisah dari karya.

Periksa lokasi tempat Anda dapat mendaftarkan paket

API pendaftaran Mermaid menerima set ikon langsung atau loader yang mengembalikannya. name yang didaftarkan menjadi prefiks yang dipakai dalam diagram. Dalam contoh ini, paketnya garden dan ikonnya leaf, sehingga referensinya garden:leaf.

Pendaftaran dilakukan dalam JavaScript yang menyiapkan renderer. Menempelkan JavaScript itu ke blok kode Mermaid bukan operasi yang sama. Jika platform publikasi Anda tidak mengizinkan konfigurasi renderer, gunakan set ikon yang didukungnya atau render diagram dalam alur yang Anda kendalikan dan sisipkan hasil ekspor. Simpan sumber Mermaid bersama hasil tersebut untuk penyuntingan berikutnya.

Untuk panduan langkah ini, gunakan halaman HTML biasa yang disajikan melalui HTTP lokal. Halaman memuat modul Mermaid 12.0.0 dengan versi tetap dari CDN sehingga memerlukan akses jaringan. Aplikasi produksi dapat membundel versi Mermaid pilihannya sendiri. Uji versi itu dan kebijakan keamanan konten host sebelum mengadopsi contoh.

Pertahankan koordinat gambar SVG

Berikut daun asli yang digunakan dalam pengujian kami. Simpan sebagai leaf.svg jika Anda ingin memeriksa karya secara terpisah:

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

Kolom body Iconify menampung konten di dalam akar SVG, tanpa elemen <svg> luarnya. Persegi panjang koordinat disampaikan secara terpisah sebagai left, top, width, dan height. Untuk file ini, titik asalnya nol dan dimensinya 32 kali 24.

Jangan menyalin ukuran CSS yang dirender sebagai gantinya. File yang ditampilkan pada 64 piksel masih dapat memiliki viewBox 0 0 32 24. Path-nya digambar dalam sistem koordinat yang terakhir itu. Untuk titik asal bukan nol, pertahankan pula nilai left dan top yang sesuai, atau sengaja translasikan karya ke kanvas dengan titik asal nol sebelum mengemasnya.

Set Iconify berisi prefix dan objek icons. Setiap key ikon menamai gambarnya. Dimensi eksplisit berguna di sini: jika ikon maupun set tidak menyediakannya, default lebar dan tinggi Iconify adalah 16. Itu dapat memotong karya yang digambar untuk kanvas lebih besar.

Jika Anda menyiapkan keluarga piktogram, selesaikan outline, padding, dan bobot visual terlebih dahulu. Panduan persiapan UI kit SVG kami membahas keputusan karya sumber tersebut. Mengemas ikon tidak memperbaiki siluetnya.

Jalankan contoh dua node yang lengkap

Simpan kode berikut sebagai index.html dalam folder baru. Jika Python tersedia, jalankan python3 -m http.server 8000 dalam folder itu, lalu buka http://localhost:8000 di 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>

Anda seharusnya melihat daun di samping simbol database, terhubung dari Source ke Library. Daun berasal dari paket terdaftar; database merupakan salah satu ikon arsitektur bawaan Mermaid. Referensi sintaks arsitektur menjelaskan nama ikon dalam tanda kurung, label dalam kurung siku, dan sisi service yang digunakan untuk edge.

Contoh menonaktifkan rendering otomatis dan membuat satu pemanggilan render() eksplisit setelah pendaftaran. Itu membuat urutannya terlihat saat pengujian. Saat mengintegrasikan ke situs yang ada, pastikan pendaftaran dan pemanggilan render memakai instance Mermaid yang sama.

Ini adalah gambar kecil tepercaya yang dibuat untuk contoh. Untuk koleksi ikon besar, gunakan alat impor dan pembersihan Iconify alih-alih menganggap setiap SVG ekspor dapat direduksi menjadi string path tanpa pekerjaan tambahan. Font, image eksternal, style, dan definisi yang dirujuk memerlukan pemeriksaan terpisah.

Bandingkan pendaftaran hilang dengan dimensi hilang

Kami merender tiga salinan diagram ini dalam dokumen browser terpisah menggunakan Mermaid 12.0.0. Salinan pertama tidak menyertakan pendaftaran. Yang kedua mendaftarkan dua path daun tetapi tidak menyertakan dimensinya. Yang ketiga mendaftarkan path yang sama dengan width: 32 dan height: 24.

Pada render pertama, Mermaid menampilkan tanda tanya di tempat daun khusus seharusnya muncul. Path daun tidak ada dalam keluaran. Pada yang kedua, keluaran berisi path itu dalam SVG dengan viewBox="0 0 16 16", dan daun terlihat terpotong. Pada yang ketiga, ikon memakai viewBox="0 0 32 24" dan daun lengkap muncul.

Pengamatan ini menjelaskan contoh dan versi tersebut. Pengamatan tidak membuktikan bahwa setiap host melaporkan ikon yang tidak tersedia dengan cara sama. Contoh juga memakai path SVG yang dibuat manual; bukan hasil konversi PerfectVector.

Simpan salinan contoh minimal yang berfungsi sebelum menambahkan ikon lain. Ubah satu properti paket setiap kali; jika tidak, perbaikan nama dapat menyembunyikan masalah ukuran terpisah.

Masukkan karya raster ke alur ketika diperlukan

Jika piktogram khusus Anda hanya tersisa sebagai PNG atau JPG, alur clipart ke SVG PerfectVector dapat membantu merekonstruksi kontur yang bisa diedit. Potong salinan hingga piktogram, pratinjau hasil vektor, dan periksa siluet, celah dalam, serta bentuk latar yang tidak diinginkan. Lalu buka SVG di editor dan siapkan versi kecil yang ingin dipakai dalam diagram.

Simpan master SVG yang bisa diedit itu. Kemas isi gambar dan koordinatnya hanya setelah terbaca jelas pada ukuran ikon yang dimaksud. Simbol geometris sederhana mungkin lebih cepat digambar ulang; foto mungkin lebih jelas sebagai gambar terpisah. Jika Anda sudah memiliki karya SVG yang sesuai, mulai dengan tahap pengemasan.

Vektorisasi tidak memulihkan nama service, hubungan, atau arah konektor diagram. Simpan semuanya dalam sumber Mermaid. Untuk editor berbasis canvas dengan perilaku bentuk berbeda, lihat bentuk SVG khusus dalam draw.io. Untuk ikon yang bisa digunakan ulang dalam halaman web biasa, sprite symbol SVG adalah jalur pengemasan lain. Untuk diagram berbasis DOT, periksa penyerahan gambar node SVG Graphviz untuk melihat apakah karya khusus ikut dalam graph ekspor.

Sebelum menyerahkan diagram, buka kembali melalui alur publikasi sebenarnya. Pastikan ikon dimuat, seluruh siluet muat, kedua label terbaca, dan konektor mengarah dengan benar. Rendering lokal yang berhasil adalah pemeriksaan awal, diikuti pemeriksaan tujuan.

FAQ

Bisakah saya memasukkan nama file SVG dalam referensi ikon Mermaid? Untuk alur paket ikon terdaftar, gunakan nama paket dan key ikon seperti garden:leaf. Siapkan gambar SVG sebagai data ikon dan daftarkan paket itu dalam JavaScript renderer.

Mengapa ikon Mermaid khusus saya terpotong? Bandingkan viewBox sumber dengan properti koordinat data ikon. Jika dimensi tidak ada pada ikon maupun set-nya, default lebar dan tinggi adalah 16, yang mungkin terlalu kecil untuk gambar.

Apakah ini bekerja dalam setiap editor Markdown yang dihosting? Tidak. Host harus mendukung sintaks diagram dan menyediakan cara mendaftarkan paket yang diperlukan, atau sudah menyertakannya. Uji tujuan publikasi sebenarnya alih-alih menganggap pengaturannya sama dengan lokal.

Sources

1. Mermaid — Mendaftarkan paket ikon — Mendokumentasikan data ikon langsung, loader, dan nama pendaftaran.
2. Mermaid — Diagram arsitektur — Mendefinisikan ikon service, label native, ikon bawaan, dan sintaks edge.
3. Iconify — IconifyIcon — Mendefinisikan isi gambar tanpa pembungkus SVG dan properti koordinat.
4. Iconify — IconifyJSON — Mendefinisikan struktur paket dan default dimensi yang diwarisi ikon.

Punya piktogram yang hanya berupa raster untuk diagram? Siapkan kandidat SVG dengan PerfectVector, periksa siluet dan celahnya, lalu daftarkan satu ikon dan verifikasi batas serta labelnya dalam renderer Mermaid akhir Anda.