> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

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

> Упакуйте свою SVG-графику в набор иконок Iconify, зарегистрируйте его в Mermaid и проверьте пропавшие иконки, обрезанные фигуры и подписи на рабочем примере схемы.

Source: https://perfectvector.com/ru/blog/mermaid-custom-svg-icons

Language: ru
Author: Irene Kim
Published: 2026-09-25T08:00:00+09:00

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

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

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

[API регистрации Mermaid](https://mermaid.ai/open-source/config/icons.html) принимает набор иконок напрямую или загрузчик, который его возвращает. Зарегистрированное `name` становится префиксом в схеме. В этом примере набор называется `garden`, а иконка — `leaf`, что даёт ссылку `garden:leaf`.

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

В этом руководстве используйте обычную HTML-страницу, доступную через локальный HTTP. Она загружает фиксированную версию модуля Mermaid 12.0.0 из CDN и поэтому требует доступа к сети. Рабочее приложение может включить выбранную версию Mermaid в свой пакет. Проверьте эту версию и политику безопасности содержимого вашей платформы перед применением примера.

## Сохраните координаты рисунка SVG

Вот исходный лист, использованный в нашем тесте. Сохраните его как `leaf.svg`, если хотите отдельно проверить иллюстрацию:

```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](https://iconify.design/docs/types/iconify-icon.html) содержит содержимое внутри корня SVG без внешнего элемента `<svg>`. Прямоугольник координат передаётся отдельно как `left`, `top`, `width` и `height`. Для этого файла начало — ноль, размеры — 32 на 24.

Не копируйте вместо них размер отображения CSS. Файл, показываемый шириной 64 пикселя, всё ещё может иметь `viewBox` `0 0 32 24`. Его контуры нарисованы в последней системе координат. Если начало ненулевое, сохраняйте и соответствующие значения `left` и `top` либо намеренно перенесите иллюстрацию на холст с нулевым началом перед упаковкой.

[Набор Iconify](https://iconify.design/docs/types/iconify-json.html) содержит `prefix` и объект `icons`. Каждый ключ иконки именует её рисунок. Явные размеры здесь полезны: если их не задаёт ни иконка, ни набор, ширина и высота Iconify по умолчанию равны 16. Это может обрезать графику, нарисованную для более крупного холста.

Если вы готовите семейство пиктограмм, сначала закончите их очертания, отступы и визуальный вес. Наше [руководство по подготовке SVG для UI-кита](https://perfectvector.com/ru/blog/convert-png-icons-to-svg-for-ui-kit) разбирает эти решения об исходной графике. Упаковка иконки не улучшает её силуэт.

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

Сохраните следующий код как `index.html` в новой папке. Если доступен Python, запустите `python3 -m http.server 8000` в этой папке, затем откройте `http://localhost:8000` в браузере.

```html
<!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. [Справочник синтаксиса архитектурных схем](https://mermaid.ai/open-source/syntax/architecture.html) описывает имена иконок в круглых скобках, подписи в квадратных и стороны сервисов, используемые для связей.

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

Это небольшой доверенный рисунок, созданный для примера. Для большой коллекции иконок используйте средства импорта и очистки Iconify, не предполагая, что любой экспортированный SVG можно свести к строке контура без дополнительной работы. Шрифты, внешние изображения, стили и ссылочные определения требуют отдельной проверки.

## Сравните отсутствие регистрации и отсутствие размеров

Мы отрисовали три копии этой схемы в отдельных браузерных документах с Mermaid 12.0.0. Первая пропускала регистрацию. Вторая регистрировала два контура листа, но не задавала их размеры. Третья регистрировала те же контуры с `width: 32` и `height: 24`.

![Три схемы Mermaid, отрисованные в браузере: вопросительный знак без регистрации иконки, обрезанный лист без размеров и полный лист с сохранённым координатным пространством 32 на 24.](https://perfectvector.com/blog/mermaid-custom-svg-icons/icon-pack-test.webp)

*Один исходный лист в Mermaid 12.0.0. Регистрация предоставляет графику; размеры задают границы координат. Подписи и соединитель остаются собственными элементами схемы.*

При первой отрисовке Mermaid показал вопросительный знак там, где должен был появиться собственный лист. Контур листа отсутствовал в выводе. Во второй вывод содержал этот контур внутри SVG с `viewBox="0 0 16 16"`, и лист был заметно обрезан. В третьей иконка использовала `viewBox="0 0 32 24"`, и появился полный лист.

Эти наблюдения относятся к данному образцу и версии. Они не подтверждают, что все платформы одинаково сообщают о недоступной иконке. Пример также использует написанные вручную контуры SVG; это не результат преобразования PerfectVector.

| Что вы видите                                                    | Первая проверка                             | Полезный следующий шаг                                                                            |
| ---------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Вопросительный знак или отсутствие собственной графики           | Регистрация, имя набора и ключ иконки       | Сопоставить `garden`, `leaf` и `garden:leaf`; убедиться, что регистрация выполняется до отрисовки |
| Только часть рисунка                                             | Координаты и размеры иконки                 | Сравнить исходный viewBox с left, top, width и height иконки                                      |
| Вся схема не работает                                            | Версия Mermaid, синтаксис и загрузка модуля | Начать с полного минимального примера и изучить сообщаемую ошибку                                 |
| Локальный пример работает, а Markdown на платформе — нет         | Возможности управления рендерером платформы | Проверить поддерживаемый механизм регистрации и фиксированную версию Mermaid                      |
| Графика появляется, но мелкие детали пропадают при размере схемы | Сложность исходника и видимый размер        | Упростить иллюстрацию или использовать более понятную пиктограмму                                 |

Сохраните рабочую копию минимального примера перед добавлением новых иконок. Меняйте по одному свойству набора; иначе исправление имени может скрыть отдельную проблему размера.

## При необходимости включите растровую графику в процесс

Если ваша пиктограмма сохранилась только в PNG или JPG, [процесс преобразования клипарта в SVG](https://perfectvector.com/ru/clipart-to-svg) PerfectVector поможет восстановить редактируемые контуры. Обрежьте копию до пиктограммы, просмотрите векторный результат и проверьте силуэт, внутренние промежутки и нежелательные фигуры фона. Затем откройте SVG в редакторе и подготовьте небольшой вариант для схемы.

Сохраните этот редактируемый SVG-оригинал. Упаковывайте графическое содержимое и координаты только после того, как оно стало ясно читаемым при нужном размере иконки. Простой геометрический символ может быть быстрее перерисовать; фотография может быть понятнее отдельным изображением. Если подходящий SVG уже есть, начните с этапа упаковки.

Векторизация не восстанавливает названия сервисов, связи или направления соединителей схемы. Храните их в исходнике Mermaid. Для редактора на холсте с другим поведением фигур см. [пользовательские SVG-фигуры в draw.io](https://perfectvector.com/ru/blog/drawio-custom-svg-shape). Для повторно используемых иконок обычной веб-страницы [спрайт символов SVG](https://perfectvector.com/ru/blog/svg-symbol-sprite) предлагает другой способ упаковки. Для схем на DOT проверьте [передачу SVG-изображений узлов Graphviz](https://perfectvector.com/ru/blog/graphviz-svg-node-images), чтобы понять, попадает ли собственная графика в экспортированный граф.

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

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

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

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

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

## Источники

1. [Mermaid — Registering icon packs](https://mermaid.ai/open-source/config/icons.html) — Описывает прямые данные иконок, загрузчики и имена регистрации.
2. [Mermaid — Architecture diagrams](https://mermaid.ai/open-source/syntax/architecture.html) — Определяет иконки сервисов, собственные подписи, встроенные иконки и синтаксис связей.
3. [Iconify — IconifyIcon](https://iconify.design/docs/types/iconify-icon.html) — Определяет графическое содержимое без оболочки SVG и координатные свойства.
4. [Iconify — IconifyJSON](https://iconify.design/docs/types/iconify-json.html) — Определяет структуру набора и размеры по умолчанию, наследуемые иконками.

***

Для схемы есть только растровая пиктограмма? [Подготовьте вариант SVG с PerfectVector](https://perfectvector.com/ru/clipart-to-svg), проверьте силуэт и промежутки, затем зарегистрируйте одну иконку и проверьте её границы и подпись в конечном рендерере Mermaid.

## Explore

- [Read the HTML article](https://perfectvector.com/ru/blog/mermaid-custom-svg-icons)
- [Импорт SVG в Excalidraw: что можно редактировать?](https://perfectvector.com/ru/blog/excalidraw-editable-svg.md)
- [Маркеры SVG: создайте правильно выровненные стрелки](https://perfectvector.com/ru/blog/svg-custom-markers.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
