Biểu tượng SVG Mermaid tùy chỉnh: Đăng ký hình của bạn

Để dùng biểu tượng SVG của bạn trong Mermaid, hãy đưa nội dung hình vẽ và kích thước tọa độ vào bộ biểu tượng Iconify, gọi mermaid.registerIconPacks() rồi tham chiếu tên đã đăng ký trong sơ đồ. Chỉ có tên tệp SVG không đăng ký được biểu tượng.

Quy trình này phù hợp với trang hoặc ứng dụng mà bạn kiểm soát JavaScript của Mermaid. Trình chỉnh sửa Markdown trực tuyến có thể chỉ cho nhập văn bản sơ đồ, nên hãy kiểm tra tùy chọn tích hợp trước khi chuẩn bị cả bộ biểu tượng. Bắt đầu với một hình biểu trưng đơn giản và một đường nối. Giữ nhãn sơ đồ trong Mermaid để chúng tách riêng với phần hình.

Kiểm tra nơi có thể đăng ký bộ biểu tượng

API đăng ký của Mermaid nhận trực tiếp một bộ biểu tượng hoặc bộ tải trả về bộ đó. name đã đăng ký trở thành tiền tố dùng trong sơ đồ. Trong ví dụ này, bộ có tên garden và biểu tượng là leaf, tạo thành tham chiếu garden:leaf.

Việc đăng ký thuộc JavaScript chuẩn bị bộ kết xuất. Dán JavaScript đó vào khối mã Mermaid không phải cùng thao tác. Nếu nền tảng xuất bản không cho cấu hình bộ kết xuất, hãy dùng các bộ biểu tượng được hỗ trợ hoặc kết xuất sơ đồ trong quy trình bạn kiểm soát rồi chèn kết quả xuất. Giữ nguồn Mermaid cùng kết quả để sửa sau này.

Trong hướng dẫn này, dùng một trang HTML thông thường được phục vụ qua HTTP cục bộ. Nó tải mô-đun Mermaid 12.0.0 cố định từ CDN nên cần truy cập mạng. Ứng dụng trong môi trường thực tế có thể đóng gói phiên bản Mermaid đã chọn. Kiểm tra phiên bản đó và chính sách bảo mật nội dung của nền tảng sử dụng trước khi áp dụng ví dụ.

Giữ tọa độ hình vẽ của SVG

Đây là chiếc lá tự tạo dùng trong phép thử. Lưu thành leaf.svg nếu muốn kiểm tra phần hình riêng:

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

Trường body của Iconify chứa nội dung bên trong phần tử gốc SVG, không gồm phần tử <svg> bên ngoài. Hình chữ nhật tọa độ được chuyển riêng qua left, top, width và height. Với tệp này, gốc tọa độ là không và kích thước là 32 × 24.

Đừng sao chép kích thước CSS hiển thị thay vào đó. Tệp hiển thị ở 64 pixel vẫn có thể có viewBox là 0 0 32 24. Đường dẫn được vẽ trong hệ tọa độ thứ hai. Với gốc tọa độ khác không, cũng giữ các giá trị left và top tương ứng, hoặc chủ động tịnh tiến phần hình về khung vẽ có gốc không trước khi đóng gói.

Bộ Iconify chứa prefix và đối tượng icons. Mỗi khóa biểu tượng đặt tên cho hình vẽ. Kích thước chỉ định rõ hữu ích ở đây: nếu cả biểu tượng lẫn bộ đều không cung cấp, chiều rộng và chiều cao mặc định của Iconify là 16. Điều đó có thể cắt mất hình vẽ cho khung lớn hơn.

Nếu chuẩn bị một họ hình biểu trưng, hãy hoàn thiện đường bao, khoảng đệm và độ nặng thị giác trước. Hướng dẫn chuẩn bị bộ giao diện SVG của chúng tôi trình bày các quyết định về phần hình nguồn đó. Đóng gói biểu tượng không cải thiện đường bao của nó.

Chạy ví dụ hoàn chỉnh có hai nút

Lưu đoạn sau thành index.html trong thư mục mới. Nếu có Python, chạy python3 -m http.server 8000 trong thư mục đó rồi mở http://localhost:8000 trong trình duyệt.

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

Bạn sẽ thấy chiếc lá cạnh biểu tượng cơ sở dữ liệu, được nối từ Source đến Library. Chiếc lá đến từ bộ đã đăng ký; database là một trong các biểu tượng kiến trúc tích hợp của Mermaid. Tài liệu cú pháp kiến trúc mô tả tên biểu tượng trong ngoặc tròn, nhãn trong ngoặc vuông và các phía của dịch vụ dùng cho cạnh nối.

Ví dụ tắt kết xuất tự động và thực hiện một lệnh gọi render() tường minh sau khi đăng ký. Điều đó giúp thấy thứ tự trong lúc thử. Khi tích hợp vào trang hiện có, đảm bảo bước đăng ký và lệnh kết xuất dùng cùng một đối tượng Mermaid.

Đây là hình nhỏ, đáng tin được tự tạo cho ví dụ. Với bộ biểu tượng lớn, dùng công cụ nhập và làm sạch của Iconify thay vì cho rằng mọi SVG xuất ra có thể rút thành chuỗi đường dẫn mà không cần làm thêm. Phông chữ, ảnh ngoài, kiểu hiển thị và định nghĩa được tham chiếu cần kiểm tra riêng.

Đối chiếu thiếu đăng ký với thiếu kích thước

Chúng tôi kết xuất ba bản sơ đồ này trong các tài liệu trình duyệt riêng bằng Mermaid 12.0.0. Bản đầu bỏ bước đăng ký. Bản thứ hai đăng ký hai đường dẫn chiếc lá nhưng bỏ kích thước. Bản thứ ba đăng ký cùng đường dẫn với width: 32 và height: 24.

Ở bản đầu, Mermaid hiển thị dấu hỏi ở nơi đáng ra có chiếc lá tùy chỉnh. Đầu ra không có đường dẫn chiếc lá. Ở bản thứ hai, đầu ra chứa đường dẫn đó trong SVG có viewBox="0 0 16 16", và chiếc lá bị cắt rõ rệt. Ở bản thứ ba, biểu tượng dùng viewBox="0 0 32 24" và chiếc lá hiện đầy đủ.

Những quan sát này mô tả mẫu thử và phiên bản này. Chúng không xác nhận mọi nền tảng sử dụng báo biểu tượng không có theo cùng cách. Ví dụ cũng dùng đường dẫn SVG tạo bằng tay; đây không phải kết quả chuyển đổi PerfectVector.

Giữ bản ví dụ tối thiểu hoạt động được trước khi thêm biểu tượng. Mỗi lần chỉ đổi một thuộc tính bộ; nếu không, sửa tên có thể che một vấn đề kích thước riêng.

Đưa hình raster vào quy trình khi cần

Nếu hình biểu trưng tùy chỉnh chỉ còn PNG hoặc JPG, quy trình clipart thành SVG của PerfectVector có thể giúp khôi phục đường bao chỉnh sửa được. Cắt bản sao vào đúng hình biểu trưng, xem trước kết quả vector và kiểm tra đường bao, khoảng trống bên trong cùng hình nền không mong muốn. Sau đó mở SVG trong trình chỉnh sửa và chuẩn bị bản nhỏ bạn định dùng trong sơ đồ.

Giữ bản gốc SVG chỉnh sửa được đó. Chỉ đóng gói nội dung hình vẽ và tọa độ sau khi nó rõ ở kích thước biểu tượng dự định. Biểu tượng hình học đơn giản có thể vẽ lại nhanh hơn; ảnh chụp có thể rõ hơn khi đặt thành ảnh riêng. Nếu đã có hình SVG phù hợp, bắt đầu từ bước đóng gói.

Vector hóa không khôi phục tên dịch vụ, mối quan hệ hay hướng đường nối trong sơ đồ. Giữ chúng trong nguồn Mermaid. Với trình chỉnh sửa dạng canvas có cách xử lý hình khác, xem hình SVG tùy chỉnh trong draw.io. Với biểu tượng tái sử dụng trên trang web thông thường, sprite symbol SVG là cách đóng gói khác. Với sơ đồ dựa trên DOT, xem bàn giao ảnh nút SVG Graphviz để biết hình tùy chỉnh có đi cùng đồ thị xuất hay không.

Trước khi bàn giao sơ đồ, mở lại qua đúng quy trình xuất bản. Xác nhận biểu tượng tải được, toàn bộ đường bao vừa khung, cả hai nhãn dễ đọc và đường nối trỏ đúng hướng. Kết xuất cục bộ thành công là bước kiểm tra đầu, sau đó cần kiểm tra tại đích tiếp nhận.

Câu hỏi thường gặp

Tôi có thể đặt tên tệp SVG trong tham chiếu biểu tượng Mermaid không? Với quy trình bộ biểu tượng đã đăng ký, dùng tên bộ và khóa biểu tượng như garden:leaf. Chuẩn bị hình SVG thành dữ liệu biểu tượng và đăng ký bộ đó trong JavaScript của bộ kết xuất.

Vì sao biểu tượng Mermaid tùy chỉnh bị cắt? Đối chiếu viewBox nguồn với thuộc tính tọa độ của dữ liệu biểu tượng. Nếu cả biểu tượng và bộ đều thiếu kích thước, chiều rộng và chiều cao mặc định là 16, có thể quá nhỏ cho hình vẽ.

Cách này có hoạt động trong mọi trình chỉnh sửa Markdown trực tuyến không? Không. Nền tảng phải hỗ trợ cú pháp sơ đồ và cung cấp cách đăng ký bộ cần thiết, hoặc đã có sẵn bộ đó. Kiểm tra đích xuất bản thực tế thay vì cho rằng nó giống cấu hình cục bộ của bạn.

Nguồn tham khảo

1. Mermaid — Đăng ký bộ biểu tượng — Mô tả dữ liệu biểu tượng trực tiếp, bộ tải và tên đăng ký.
2. Mermaid — Sơ đồ kiến trúc — Định nghĩa biểu tượng dịch vụ, nhãn gốc, biểu tượng tích hợp và cú pháp cạnh nối.
3. Iconify — IconifyIcon — Định nghĩa nội dung hình vẽ không có phần bọc SVG và các thuộc tính tọa độ.
4. Iconify — IconifyJSON — Định nghĩa cấu trúc bộ và kích thước mặc định mà biểu tượng kế thừa.

Bạn có hình biểu trưng chỉ ở dạng raster cho sơ đồ? Chuẩn bị bản SVG ứng viên bằng PerfectVector, kiểm tra đường bao và khoảng trống, rồi đăng ký một biểu tượng và xác minh giới hạn cùng nhãn trong bộ kết xuất Mermaid cuối cùng.