Свои SVG-иконки Mermaid: регистрация иллюстрации

Чтобы использовать свою SVG-иконку в Mermaid, поместите её графическое содержимое и размеры системы координат в набор иконок Iconify, вызовите mermaid.registerIconPacks() и укажите зарегистрированное имя в схеме. Одно имя SVG-файла не регистрирует иконку.

Этот процесс подходит странице или приложению, где вы управляете JavaScript Mermaid. Размещённый в онлайн-сервисе Markdown-редактор может предоставлять доступ только к тексту схемы, поэтому проверьте возможности интеграции перед подготовкой целой коллекции иконок. Начните с одной простой пиктограммы и одного соединителя. Храните подписи схемы в Mermaid, отдельно от графики.

Проверьте, где можно зарегистрировать набор

API регистрации Mermaid принимает набор иконок напрямую или загрузчик, который его возвращает. Зарегистрированное name становится префиксом в схеме. В этом примере набор называется garden, а иконка — leaf, что даёт ссылку garden:leaf.

Регистрация должна находиться в JavaScript, который подготавливает рендерер. Вставка этого JavaScript в блок кода Mermaid — другая операция. Если платформа публикации не позволяет настроить рендерер, используйте поддерживаемые ею наборы иконок или отрисуйте схему в контролируемом вами процессе и вставьте экспортированный результат. Сохраните рядом с ним исходник Mermaid для последующих правок.

В этом руководстве используйте обычную HTML-страницу, доступную через локальный HTTP. Она загружает фиксированную версию модуля Mermaid 12.0.0 из CDN и поэтому требует доступа к сети. Рабочее приложение может включить выбранную версию 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-кита разбирает эти решения об исходной графике. Упаковка иконки не улучшает её силуэт.

Запустите полный пример с двумя узлами

Сохраните следующий код как 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 — одна из встроенных архитектурных иконок Mermaid. Справочник синтаксиса архитектурных схем описывает имена иконок в круглых скобках, подписи в квадратных и стороны сервисов, используемые для связей.

Пример отключает автоматическую отрисовку и делает один явный вызов render() после регистрации. Так порядок действий виден при тестировании. При интеграции в существующий сайт убедитесь, что регистрация и вызов отрисовки используют один экземпляр Mermaid.

Это небольшой доверенный рисунок, созданный для примера. Для большой коллекции иконок используйте средства импорта и очистки 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 уже есть, начните с этапа упаковки.

Векторизация не восстанавливает названия сервисов, связи или направления соединителей схемы. Храните их в исходнике Mermaid. Для редактора на холсте с другим поведением фигур см. пользовательские SVG-фигуры в draw.io. Для повторно используемых иконок обычной веб-страницы спрайт символов SVG предлагает другой способ упаковки. Для схем на DOT проверьте передачу SVG-изображений узлов Graphviz, чтобы понять, попадает ли собственная графика в экспортированный граф.

Перед передачей схемы заново откройте её через реальный процесс публикации. Убедитесь, что иконка загружается, весь силуэт помещается, обе подписи читаются, а соединитель направлен правильно. Успешная локальная отрисовка — первая проверка, за которой следует проверка в целевой среде.

Частые вопросы

Можно ли поместить имя SVG-файла в ссылку на иконку Mermaid? Для процесса с зарегистрированным набором иконок используйте имя набора и ключ иконки, например garden:leaf. Подготовьте SVG-рисунок как данные иконки и зарегистрируйте набор в JavaScript рендерера.

Почему моя собственная иконка Mermaid обрезана? Сравните исходный viewBox с координатными свойствами данных иконки. Если размеры отсутствуют и в иконке, и в наборе, ширина и высота по умолчанию равны 16, чего может быть недостаточно для рисунка.

Работает ли это в любом онлайн-редакторе Markdown? Нет. Платформа должна поддерживать синтаксис схемы и предоставлять способ регистрации нужного набора или уже включать его. Проверяйте реальное место публикации, не предполагая совпадения с локальной настройкой.

Источники

1. Mermaid — Registering icon packs — Описывает прямые данные иконок, загрузчики и имена регистрации.
2. Mermaid — Architecture diagrams — Определяет иконки сервисов, собственные подписи, встроенные иконки и синтаксис связей.
3. Iconify — IconifyIcon — Определяет графическое содержимое без оболочки SVG и координатные свойства.
4. Iconify — IconifyJSON — Определяет структуру набора и размеры по умолчанию, наследуемые иконками.

Для схемы есть только растровая пиктограмма? Подготовьте вариант SVG с PerfectVector, проверьте силуэт и промежутки, затем зарегистрируйте одну иконку и проверьте её границы и подпись в конечном рендерере Mermaid.