Ícones SVG no Mermaid: registre sua própria arte

Para usar seu próprio ícone SVG no Mermaid, coloque seu conteúdo de desenho e suas dimensões de coordenadas em um conjunto de ícones Iconify, chame mermaid.registerIconPacks() e referencie o nome registrado no diagrama. Um nome de arquivo SVG sozinho não registra um ícone.

Este fluxo atende a uma página ou aplicação em que você controla o JavaScript do Mermaid. Um editor Markdown hospedado pode expor apenas o texto do diagrama, portanto confira suas opções de integração antes de preparar uma coleção inteira de ícones. Comece com um pictograma simples e um conector. Mantenha os rótulos do diagrama no Mermaid para que permaneçam separados da arte.

Confira onde você pode registrar o pacote

A API de registro do Mermaid aceita um conjunto de ícones diretamente ou um carregador que retorne um. O name registrado se torna o prefixo usado no diagrama. Neste exemplo, o pacote é garden e seu ícone é leaf, resultando na referência garden:leaf.

O registro pertence ao JavaScript que prepara o renderizador. Colar esse JavaScript em um bloco de código Mermaid não é a mesma operação. Se a plataforma de publicação não permitir configurar seu renderizador, use os conjuntos de ícones compatíveis com ela ou renderize o diagrama em um fluxo que você controla e insira o resultado exportado. Guarde a origem Mermaid junto desse resultado para edições futuras.

Neste passo a passo, use uma página HTML comum servida por HTTP local. Ela carrega um módulo Mermaid 12.0.0 com versão fixada de uma CDN e, portanto, precisa de acesso à rede. Uma aplicação de produção pode empacotar a versão Mermaid escolhida. Teste essa versão e a política de segurança de conteúdo da hospedagem antes de adotar o exemplo.

Preserve as coordenadas de desenho do SVG

Aqui está a folha original usada em nosso teste. Salve-a como leaf.svg se quiser inspecionar a arte separadamente:

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

O campo body do Iconify contém o conteúdo dentro da raiz SVG, sem o elemento externo <svg>. O retângulo de coordenadas é informado separadamente como left, top, width e height. Para este arquivo, a origem é zero e as dimensões são 32 por 24.

Não copie o tamanho CSS renderizado. Um arquivo exibido com 64 pixels ainda pode ter um viewBox de 0 0 32 24. Seus traçados foram desenhados nesse último sistema de coordenadas. Para uma origem diferente de zero, preserve também os valores correspondentes de left e top, ou translade deliberadamente a arte para uma área de desenho com origem zero antes de empacotá-la.

Um conjunto Iconify contém um prefix e um objeto icons. Cada chave de ícone nomeia seu desenho. Dimensões explícitas são úteis aqui: se nem o ícone nem o conjunto as fornecerem, os padrões de largura e altura do Iconify são 16. Isso pode recortar arte desenhada para uma área maior.

Se você estiver preparando uma família de pictogramas, finalize primeiro seu contorno, espaçamento e peso visual. Nosso guia de preparação de kits de interface SVG aborda essas decisões da arte de origem. Empacotar um ícone não melhora sua silhueta.

Execute um exemplo completo de dois nós

Salve o seguinte como index.html em uma pasta nova. Se Python estiver disponível, execute python3 -m http.server 8000 nessa pasta e abra http://localhost:8000 no navegador.

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

Você deve ver a folha ao lado de um símbolo de banco de dados, conectados de Source a Library. A folha vem do pacote registrado; database é um dos ícones de arquitetura integrados do Mermaid. A referência de sintaxe de arquitetura descreve nomes de ícones entre parênteses, rótulos entre colchetes e os lados dos serviços usados pelas arestas.

O exemplo desativa a renderização automática e faz uma chamada explícita render() após o registro. Isso deixa a ordem visível durante o teste. Ao integrá-lo a um site existente, garanta que o registro e a chamada de renderização usem a mesma instância Mermaid.

Este é um desenho pequeno e confiável criado para o exemplo. Para uma grande coleção de ícones, use as ferramentas de importação e limpeza do Iconify em vez de presumir que todo SVG exportado possa ser reduzido a uma string de traçados sem trabalho adicional. Fontes, imagens externas, estilos e definições referenciadas merecem uma inspeção separada.

Compare registro ausente com dimensões ausentes

Renderizamos três cópias deste diagrama em documentos de navegador separados usando Mermaid 12.0.0. A primeira omitiu o registro. A segunda registrou os dois traçados da folha, mas omitiu suas dimensões. A terceira registrou os mesmos traçados com width: 32 e height: 24.

Na primeira renderização, o Mermaid exibiu um ponto de interrogação onde a folha personalizada deveria aparecer. O traçado da folha estava ausente da saída. Na segunda, a saída continha esse traçado dentro de um SVG com viewBox="0 0 16 16", e a folha estava visivelmente recortada. Na terceira, o ícone usou viewBox="0 0 32 24" e a folha completa apareceu.

Essas observações descrevem este exemplo e esta versão. Elas não estabelecem que toda hospedagem informe um ícone indisponível da mesma forma. O exemplo também usa traçados SVG criados manualmente; não é um resultado de conversão do PerfectVector.

Guarde uma cópia funcional do exemplo mínimo antes de adicionar mais ícones. Mude uma propriedade do pacote por vez; caso contrário, uma correção de nome pode esconder um problema separado de tamanho.

Traga arte raster para o fluxo quando necessário

Se seu pictograma personalizado existe apenas como PNG ou JPG, o fluxo de clipart para SVG do PerfectVector pode ajudar a recuperar contornos editáveis. Recorte uma cópia para o pictograma, confira o resultado vetorial e inspecione a silhueta, os espaços internos e as formas indesejadas de fundo. Depois abra o SVG em um editor e prepare a versão pequena que pretende usar no diagrama.

Guarde esse original SVG editável. Empacote seu conteúdo de desenho e suas coordenadas apenas depois de ele ficar claro no tamanho pretendido de ícone. Um símbolo geométrico simples pode ser mais rápido de redesenhar; uma fotografia pode ficar mais clara como imagem separada. Se você já tem arte SVG adequada, comece pela etapa de empacotamento.

A vetorização não recupera os nomes de serviços, relacionamentos ou direções dos conectores do diagrama. Mantenha-os na origem Mermaid. Para um editor baseado em canvas com comportamento diferente de formas, veja formas SVG personalizadas no draw.io. Para ícones reutilizáveis em uma página web comum, um sprite de símbolos SVG é outro caminho de empacotamento. Para diagramas baseados em DOT, confira a entrega de imagens SVG de nós Graphviz para ver se a arte personalizada acompanha o grafo exportado.

Antes de entregar o diagrama, reabra-o pelo fluxo real de publicação. Confirme que o ícone carrega, que a silhueta completa cabe, que ambos os rótulos são legíveis e que o conector aponta na direção certa. Uma renderização local bem-sucedida é a verificação inicial, seguida de uma verificação no destino.

Perguntas frequentes

Posso colocar um nome de arquivo SVG dentro de uma referência de ícone Mermaid? No fluxo de pacote de ícones registrado, use um nome de pacote e uma chave de ícone, como garden:leaf. Prepare o desenho SVG como dados de ícone e registre esse pacote no JavaScript do renderizador.

Por que meu ícone Mermaid personalizado está recortado? Compare o viewBox de origem com as propriedades de coordenadas dos dados do ícone. Se as dimensões estiverem ausentes tanto do ícone quanto de seu conjunto, os padrões de largura e altura são 16, o que pode ser pequeno demais para o desenho.

Isso funciona em todo editor Markdown hospedado? Não. A hospedagem precisa suportar a sintaxe do diagrama e oferecer uma forma de registrar o pacote necessário, ou já incluí-lo. Teste o destino real de publicação em vez de presumir que ele compartilhe sua configuração local.

Fontes

1. Mermaid — Registro de pacotes de ícones — Documenta dados diretos de ícones, carregadores e nomes de registro.
2. Mermaid — Diagramas de arquitetura — Define ícones de serviço, rótulos nativos, ícones integrados e sintaxe de arestas.
3. Iconify — IconifyIcon — Define conteúdo de desenho sem o invólucro SVG e propriedades de coordenadas.
4. Iconify — IconifyJSON — Define a estrutura do pacote e os padrões de dimensões herdados pelos ícones.

Tem um pictograma apenas raster para seu diagrama? Prepare um candidato SVG com o PerfectVector, inspecione sua silhueta e seus espaços, registre um ícone e verifique seus limites e seu rótulo no renderizador Mermaid final.