ไอคอน SVG ใน Mermaid: ลงทะเบียนภาพของคุณ

หากต้องการใช้ไอคอน SVG ของคุณใน Mermaid ให้นำเนื้อหาภาพและขนาดพิกัดใส่ในชุดไอคอน Iconify เรียก mermaid.registerIconPacks() แล้วอ้างชื่อที่ลงทะเบียนในแผนภาพ ชื่อไฟล์ SVG อย่างเดียวไม่ได้ลงทะเบียนไอคอน

วิธีนี้เหมาะกับหน้าเว็บหรือแอปที่คุณควบคุม JavaScript ของ Mermaid ตัวแก้ไข Markdown ที่มีผู้ให้บริการอาจเปิดให้ใช้เฉพาะข้อความแผนภาพ จึงตรวจตัวเลือกการเชื่อมต่อก่อนเตรียมทั้งชุดไอคอน เริ่มด้วยรูปสัญลักษณ์ง่ายหนึ่งรูปและเส้นเชื่อมหนึ่งเส้น เก็บป้ายแผนภาพใน Mermaid เพื่อให้แยกจากภาพ

ตรวจว่าลงทะเบียนชุดได้ที่ไหน

API ลงทะเบียนของ Mermaid รับชุดไอคอนโดยตรงหรือ loader ที่คืนชุดไอคอน name ที่ลงทะเบียนเป็นคำนำหน้าในแผนภาพ ตัวอย่างนี้ใช้ชุด garden และไอคอน leaf จึงอ้างเป็น garden:leaf

การลงทะเบียนต้องอยู่ใน JavaScript ที่เตรียมตัวเรนเดอร์ การวาง JavaScript นั้นในบล็อกโค้ด Mermaid ไม่ใช่การทำงานเดียวกัน หากแพลตฟอร์มเผยแพร่ไม่ให้กำหนดตัวเรนเดอร์ ใช้ชุดไอคอนที่รองรับ หรือเรนเดอร์ในกระบวนการที่คุณควบคุมแล้วแทรกผลส่งออก เก็บต้นทาง Mermaid ควบคู่ผลนั้นไว้แก้ภายหลัง

สำหรับคู่มือนี้ ใช้หน้า HTML ปกติที่ให้บริการผ่าน HTTP ในเครื่อง มันโหลดโมดูล Mermaid 12.0.0 ที่กำหนดเวอร์ชันจาก CDN จึงต้องเข้าถึงเครือข่าย แอปใช้งานจริงอาจ bundle เวอร์ชัน Mermaid ที่เลือกแทน ทดสอบเวอร์ชันนั้นและนโยบายความปลอดภัยเนื้อหาของโฮสต์ก่อนใช้ตัวอย่าง

รักษาพิกัดภาพ SVG

นี่คือใบไม้ต้นฉบับที่ใช้ทดสอบ บันทึกเป็น leaf.svg หากต้องการตรวจภาพแยก:

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

ฟิลด์ body ของ Iconify เก็บเนื้อหาภายในราก SVG โดยไม่รวม <svg> ชั้นนอก กรอบพิกัดส่งแยกเป็น left, top, width และ height ไฟล์นี้มีจุดกำเนิดศูนย์และขนาด 32 คูณ 24

อย่าคัดลอกขนาด CSS ที่แสดงแทน ไฟล์ที่แสดง 64 พิกเซลอาจมี viewBox เป็น 0 0 32 24 พาธวาดในระบบพิกัดหลังนี้ หากจุดกำเนิดไม่ใช่ศูนย์ ให้รักษา left และ top ที่สอดคล้องด้วย หรือจงใจเลื่อนภาพไปยังพื้นที่วาดที่เริ่มศูนย์ก่อนจัดแพ็กเกจ

ชุด Iconify มี prefix และวัตถุ icons แต่ละคีย์ไอคอนตั้งชื่อภาพ การระบุขนาดชัดมีประโยชน์ เพราะหากทั้งไอคอนและชุดไม่ระบุ Iconify ใช้ความกว้างและสูงเริ่มต้น 16 ซึ่งอาจตัดภาพที่วาดสำหรับพื้นที่ใหญ่กว่า

หากเตรียมชุดรูปสัญลักษณ์ ให้ทำเส้นรอบนอก ระยะเผื่อ และน้ำหนักภาพให้เสร็จก่อน คู่มือเตรียม SVG UI kit ของเราอธิบายการตัดสินใจเรื่องภาพต้นทางเหล่านี้ การจัดแพ็กเกจไอคอนไม่ได้ทำให้ขอบรูปดีขึ้น

รันตัวอย่างสองโหนดฉบับสมบูรณ์

บันทึกเป็น index.html ในโฟลเดอร์ใหม่ หากมี Python รัน python3 -m http.server 8000 ในโฟลเดอร์นั้น แล้วเปิด http://localhost:8000 ในเบราว์เซอร์

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

ควรเห็นใบไม้ข้างสัญลักษณ์ฐานข้อมูล เชื่อมจาก Source ไป Library ใบไม้มาจากชุดที่ลงทะเบียน ส่วน database เป็นไอคอน architecture ในตัวของ Mermaid เอกสารไวยากรณ์ architecture อธิบายชื่อไอคอนในวงเล็บกลม ป้ายในวงเล็บเหลี่ยม และด้านของ service ที่ใช้กับเส้นเชื่อม

ตัวอย่างปิดการเรนเดอร์อัตโนมัติ และเรียก render() ชัดเจนครั้งเดียวหลังลงทะเบียน ทำให้เห็นลำดับระหว่างทดสอบ เมื่อนำเข้าเว็บที่มีอยู่ ยืนยันว่าการลงทะเบียนและเรียกเรนเดอร์ใช้ Mermaid instance เดียวกัน

นี่เป็นภาพวาดเล็กที่เชื่อถือได้และสร้างสำหรับตัวอย่าง สำหรับชุดไอคอนใหญ่ ให้ใช้เครื่องมือนำเข้าและทำความสะอาดของ Iconify แทนการคิดว่า SVG ทุกไฟล์ที่ส่งออกลดเป็นสตริงพาธได้โดยไม่ทำงานเพิ่ม ฟอนต์ ภาพภายนอก สไตล์ และนิยามที่อ้างอิงต้องตรวจแยก

เปรียบเทียบการไม่ลงทะเบียนกับการไม่ระบุขนาด

เราเรนเดอร์แผนภาพนี้สามสำเนาในเอกสารเบราว์เซอร์แยกด้วย Mermaid 12.0.0 แบบแรกละการลงทะเบียน แบบที่สองลงทะเบียนพาธใบไม้สองพาธแต่ไม่ระบุขนาด แบบที่สามลงทะเบียนพาธเดิมพร้อม width: 32 และ height: 24

ในการเรนเดอร์แรก Mermaid แสดงเครื่องหมายคำถามแทนใบไม้ที่กำหนดเอง พาธใบไม้ไม่มีในผลลัพธ์ แบบที่สองมีพาธนั้นภายใน SVG ที่มี viewBox="0 0 16 16" และใบไม้ถูกตัดให้เห็นชัด แบบที่สามใช้ viewBox="0 0 32 24" และใบไม้แสดงครบ

ข้อสังเกตเหล่านี้อธิบายตัวอย่างและเวอร์ชันนี้ ไม่ได้ยืนยันว่าโฮสต์ทุกตัวรายงานไอคอนไม่มีเหมือนกัน ตัวอย่างใช้พาธ SVG ที่เขียนด้วยมือด้วย ไม่ใช่ผลแปลง PerfectVector

เก็บสำเนาตัวอย่างขั้นต่ำที่ทำงานได้ก่อนเพิ่มไอคอน เปลี่ยนพร็อพเพอร์ตีชุดทีละตัว มิฉะนั้นการแก้ชื่ออาจซ่อนปัญหาขนาดอีกอย่าง

นำภาพราสเตอร์เข้าสู่กระบวนการเมื่อจำเป็น

หากรูปสัญลักษณ์ของคุณเหลือเพียง PNG หรือ JPG กระบวนการคลิปอาร์ตเป็น SVG ของ PerfectVector ช่วยสร้างเส้นรอบรูปที่แก้ได้กลับมา ครอบสำเนาเฉพาะรูปสัญลักษณ์ ดูตัวอย่างเวกเตอร์ และตรวจขอบรูป ช่องภายใน และรูปทรงพื้นหลังที่ไม่ต้องการ จากนั้นเปิด SVG ในโปรแกรมแก้ไขและเตรียมแบบเล็กที่ตั้งใจใช้ในแผนภาพ

เก็บ SVG หลักที่แก้ไขได้ จัดแพ็กเกจเนื้อหาภาพและพิกัดหลังจากอ่านภาพได้ชัดที่ขนาดไอคอนใช้งานเท่านั้น สัญลักษณ์เรขาคณิตง่ายอาจวาดใหม่เร็วกว่า ภาพถ่ายอาจชัดกว่าเมื่อเป็นภาพแยก หากมี SVG เหมาะสมอยู่แล้ว ให้เริ่มที่ขั้นตอนจัดแพ็กเกจ

การแปลงเวกเตอร์ไม่คืนชื่อ service ความสัมพันธ์ หรือทิศเส้นเชื่อมของแผนภาพ เก็บสิ่งเหล่านั้นในต้นทาง Mermaid สำหรับโปรแกรมแบบ canvas ที่มีพฤติกรรมรูปร่างต่างกัน ดูรูปร่าง SVG ที่กำหนดเองใน draw.io สำหรับไอคอนใช้ซ้ำบนเว็บปกติ SVG symbol sprite เป็นอีกวิธีจัดแพ็กเกจ สำหรับแผนภาพ DOT ตรวจการส่งมอบภาพโหนด SVG ใน Graphviz เพื่อดูว่าภาพกำหนดเองไปกับกราฟส่งออกหรือไม่

ก่อนส่งมอบแผนภาพ เปิดใหม่ผ่านกระบวนการเผยแพร่จริง ยืนยันว่าไอคอนโหลด ขอบรูปทั้งหมดพอดี ป้ายทั้งสองอ่านได้ และเส้นเชื่อมชี้ถูกทาง การเรนเดอร์ในเครื่องสำเร็จเป็นการตรวจเริ่มต้น ตามด้วยการตรวจปลายทาง

คำถามที่พบบ่อย

ใส่ชื่อไฟล์ SVG ในการอ้างอิงไอคอน Mermaid ได้หรือไม่? สำหรับวิธีชุดไอคอนลงทะเบียน ใช้ชื่อชุดและคีย์ไอคอน เช่น garden:leaf เตรียมภาพ SVG เป็นข้อมูลไอคอนแล้วลงทะเบียนชุดนั้นใน JavaScript ของตัวเรนเดอร์

ทำไมไอคอน Mermaid ที่กำหนดเองถูกตัด? เทียบ viewBox ต้นทางกับพร็อพเพอร์ตีพิกัดในข้อมูลไอคอน หากทั้งไอคอนและชุดไม่มีขนาด ค่าเริ่มต้นความกว้างและสูงเป็น 16 ซึ่งอาจเล็กเกินภาพ

ใช้ได้ในตัวแก้ไข Markdown บนโฮสต์ทุกตัวหรือไม่? ไม่ โฮสต์ต้องรองรับไวยากรณ์แผนภาพและมีวิธีลงทะเบียนชุดที่ต้องใช้ หรือรวมชุดไว้อยู่แล้ว ทดสอบปลายทางเผยแพร่จริง แทนการคิดว่าเหมือนชุดในเครื่อง

แหล่งอ้างอิง

1. Mermaid — การลงทะเบียนชุดไอคอน — อธิบายข้อมูลไอคอนโดยตรง loader และชื่อที่ลงทะเบียน
2. Mermaid — แผนภาพ Architecture — นิยามไอคอน service ป้ายของโปรแกรม ไอคอนในตัว และไวยากรณ์เส้นเชื่อม
3. Iconify — IconifyIcon — นิยามเนื้อหาภาพที่ไม่รวมตัวห่อ SVG และพร็อพเพอร์ตีพิกัด
4. Iconify — IconifyJSON — นิยามโครงสร้างชุดและค่าเริ่มต้นขนาดที่ไอคอนรับทอด

มีรูปสัญลักษณ์ราสเตอร์ล้วนสำหรับแผนภาพใช่ไหม? เตรียม SVG สำหรับประเมินด้วย PerfectVector ตรวจขอบรูปและช่องว่าง แล้วลงทะเบียนไอคอนหนึ่งตัวและตรวจขอบเขตกับป้ายในตัวเรนเดอร์ Mermaid สุดท้าย