Importar SVG no Konva: imagem ou traçados editáveis

Use Konva.Image quando quiser inserir um SVG completo em um canvas. Use nós Konva.Path separados quando seu aplicativo precisar recolorir ou manipular formas de traçado individuais. Carregar uma imagem SVG não cria automaticamente um objeto Konva para cada elemento dentro dela. O guia de SVG do Konva descreve essas opções como abordagens diferentes.

Para um seletor de logos ou uma ferramenta de composição, uma imagem pode bastar. Para um emblema de duas cores cujas regiões precisam de controles separados, a estrutura dos objetos importa. Decida o que o usuário precisa editar antes de escolher o carregador e mantenha o SVG original junto da cena do canvas.

Escolha a representação antes de importar

O tutorial de Path do Konva aceita dados de traçado SVG por meio de data. Esse é o valor do atributo d de um traçado, não o documento SVG completo. Copiar apenas os valores d não transfere com eles a transformação do grupo pai, a cor herdada ou o comportamento do viewBox do SVG.

Também existe uma questão separada sobre o arquivo de origem: o SVG contém traçados? Use o guia de inspeção de raster incorporado quando a arte é um bitmap envolvido em SVG. Um SVG válido baseado em traçados ainda pode se tornar um único nó de imagem no Konva; isso não torna o arquivo de origem um falso vetor.

Um exemplo de duas cores com um teste visível de preenchimento

A marca original abaixo contém dois traçados feitos manualmente com preenchimentos explícitos. O canvas esquerdo carrega os dois como uma única imagem. O direito constrói dois nós Path a partir da mesma geometria. Ambos recebem uma solicitação de preenchimento rosa e uma escala de 1.3.

O retângulo rosa à esquerda é uma evidência útil: imageNode.fill() altera o fundo da forma de imagem, enquanto as regiões opacas verde e amarela mantêm suas cores de origem. À direita, paths[0].fill() altera somente a primeira região. Este teste usa geometria original, não um resultado de conversão do PerfectVector.

Salve o seguinte como um arquivo HTML e sirva-o pelo seu servidor local de desenvolvimento. Ele fixa o Konva 10.6.0, cria dois palcos de 320 × 240 e espera que a imagem SVG seja decodificada antes de desenhar. O código é a mesma comparação executada para a captura.

<div id="image-scene"></div>
<div id="path-scene"></div>
<script src="https://unpkg.com/konva@10.6.0/konva.min.js"></script>
<script type="module">
const parts = [
  { data: 'M20 80 C20 30 70 20 100 40 L100 140 C60 140 20 120 20 80 Z', fill: '#176b55' },
  { data: 'M100 40 C150 20 180 50 180 85 C180 120 145 140 100 140 Z', fill: '#e9b949' }
];
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="200" height="160" viewBox="0 0 200 160">${parts.map(p => `<path d="${p.data}" fill="${p.fill}"/>`).join('')}</svg>`;
const source = new Image();
source.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
await source.decode();
 
function makeStage(container) {
  const stage = new Konva.Stage({ container, width: 320, height: 240 });
  const layer = new Konva.Layer();
  stage.add(layer);
  return { stage, layer };
}
const imageScene = makeStage('image-scene');
const pathScene = makeStage('path-scene');
const imageNode = new Konva.Image({
  image: source, x: 30, y: 16, width: 200, height: 160
});
imageScene.layer.add(imageNode);
const group = new Konva.Group({ x: 30, y: 16 });
const paths = parts.map(p => new Konva.Path(p));
group.add(...paths);
pathScene.layer.add(group);
 
// Compare the same fill request on the two representations.
imageNode.fill('#db567d');
paths[0].fill('#db567d');
 
// Resize both without changing their source geometry.
imageNode.scale({ x: 1.3, y: 1.3 });
group.scale({ x: 1.3, y: 1.3 });
imageScene.layer.draw();
pathScene.layer.draw();
 
const png = pathScene.stage.toDataURL({ pixelRatio: 2 });
const exported = new Image();
exported.src = png;
await exported.decode();
</script>

Neste exemplo deliberadamente pequeno, cada traçado tem sua própria pintura e usa as mesmas coordenadas. O grupo dá aos dois traçados editáveis uma única posição e escala. Alterar a escala do grupo mantém intacto o data de cada traçado; muda onde e em que tamanho o grupo desenha.

Para um arquivo SVG confiável existente que só precisa ser posicionado como imagem inteira, o tutorial de Image mostra o fluxo normal de carregamento de imagem. Carregue a URL SVG como imagem, espere que ela carregue e passe-a para Konva.Image. Um componente React que renderiza marcação SVG é um valor diferente do objeto de imagem que o canvas espera.

Transfira mais do que dados de traçado quando a arte for complexa

O array parts do exemplo é um modelo explícito de duas formas conhecidas. Ele não é um importador SVG. Antes de usar uma abordagem semelhante em uma arte exportada, inspecione o que cria sua aparência:

• Uma transformação de grupo pode mover, girar ou escalar todos os filhos. Preserve essa relação ou incorpore deliberadamente a transformação à geometria.
• A pintura pode vir de um ancestral ou de uma regra CSS. Resolva o preenchimento e o contorno pretendidos, em vez de supor que cada traçado os declara.
• Gradientes, recortes, máscaras e filtros têm suas próprias definições e referências. Uma string d copiada não reconstrói esses efeitos.
• Texto e formas básicas podem precisar de tratamento separado. Não suponha que todo objeto visível já é um traçado.

Mantenha uma renderização do original ao lado da sua reconstrução durante os testes. Comece com uma região reconhecível, compare sua posição e cor e só então acrescente as formas restantes. O guia de edição de SVG aborda a limpeza do arquivo original quando é difícil trabalhar com a estrutura dos objetos.

Se controles individuais de traçado forem desnecessários, carregar o SVG completo como imagem pode evitar esse trabalho de reconstrução. O Konva também documenta a renderização de SVG com uma biblioteca externa, como canvg, seguida da inserção do canvas resultante em um Konva.Image. Isso continua sendo uma representação como imagem; não fornece ao usuário nós Konva separados para cada traçado de origem. Veja as opções documentadas.

Para uma arte que só precisa de outra cor no SVG original, outra abordagem é atualizar o próprio SVG e recarregar sua imagem. O mantenedor do Konva descreve esse fluxo na issue 530 do react-konva. Use uma edição estruturada adequada ao seu SVG conhecido, em vez de substituir indiscriminadamente todos os preenchimentos e perder diferenças intencionais de cor.

Trate a exportação do canvas como entrega raster

O exemplo chama pathScene.stage.toDataURL({ pixelRatio: 2 }). Seu palco de 320 × 240 produz um PNG decodificado de 640 × 480. Aumentar pixelRatio muda as dimensões em pixels da exportação; não transforma o PNG em SVG editável. A documentação de exportação do Konva explica essa configuração.

Mantenha estas três entregas separadas:

1. O SVG original, para edição vetorial e comparação.
2. Os dados da cena do seu aplicativo, incluindo referências a traçados ou imagens e as edições que seu aplicativo permite.
3. Um PNG ou outra exportação raster, para usos que precisam de uma imagem renderizada.

Reabra o PNG exportado e inspecione suas dimensões e pequenos detalhes. Teste também a imagem SVG nos navegadores compatíveis com seu aplicativo; o guia de SVG do Konva observa diferenças de compatibilidade de renderização. Este exemplo testa um SVG simples e autossuficiente, portanto não demonstra suporte a todos os arquivos ou efeitos exportados.

Evite avaliar a qualidade vetorial apenas pela prévia do canvas. O guia de SVG pixelado separa a geometria de origem das prévias raster e do dimensionamento de exibição.

Quando o PerfectVector ajuda com a imagem original

Se seu recurso inicial é somente um motivo PNG ou JPG, o PerfectVector pode ajudar a reconstruir geometria SVG editável antes de você construir a cena do Konva. Converta a imagem para vetor, abra o resultado em um editor e inspecione a silhueta, os vazados e as regiões de cor antes de mapear quaisquer traçados para seu aplicativo.

A vetorização não cria um modelo de cena do Konva nem um interpretador SVG arbitrário. Você ainda escolhe a representação e transfere as propriedades de que ela precisa. Se já tem um mestre SVG utilizável, trabalhe com esse arquivo. Para fotografia ou textura pintada que deve continuar como pixels, um nó de imagem costuma ser a representação adequada, sem vetorização.

Confira a importação com sua própria arte

Antes de adicionar um SVG a um editor reutilizável:

1. Escolha um único nó de imagem inteira ou nós de formas separados conforme os controles de que o usuário precisa.
2. Altere a cor de uma região e confirme que somente o objeto pretendido muda.
3. Redimensione o desenho completo e confira o espaçamento, a aparência do contorno e o recorte.
4. Exporte nas dimensões em pixels necessárias e reabra o arquivo raster.
5. Reabra o mestre SVG salvo de forma independente, para que uma exportação do canvas nunca se torne sua única cópia.

Perguntas frequentes

Konva.Image torna editáveis os traçados dentro de um SVG? Não. Ele exibe o SVG como um único nó de imagem. Para controlar regiões individuais de traçado, crie nós Path separados a partir de dados de traçado adequados ou use um fluxo de edição SVG que preserve a estrutura do documento.

Por que fill adiciona um retângulo em vez de recolorir meu SVG? Em um nó Image, o preenchimento pinta a forma da imagem atrás de seu conteúdo. Ele não reescreve os preenchimentos dentro do SVG. Edite o SVG de origem e recarregue-o, ou use nós Path separados quando seu aplicativo precisar de controles individuais de cor.

Aumentar pixelRatio exporta um arquivo vetorial? Não. Neste exemplo, pixelRatio 2 produz um PNG com o dobro da largura e da altura do palco. Mantenha o SVG original separadamente para edição vetorial.

Fontes

1. Konva — SVG no canvas — Explica as opções Image, Path e renderizador externo e os limites de compatibilidade entre navegadores.
2. Konva — tutorial de Path — Documenta a construção de um Path a partir de dados de traçado SVG e propriedades explícitas de pintura.
3. Konva — tutorial de Image — Mostra o carregamento de uma imagem e sua inserção em uma cena Konva.
4. Konva — exportação de imagem em alta qualidade — Explica a exportação raster e o efeito de pixelRatio nas dimensões de saída.
5. Konva — issue 530 do react-konva — Registra a abordagem do mantenedor de editar o SVG original e recarregá-lo para alterar cores de imagens SVG.

Você está começando com um ícone disponível somente em raster? Transforme sua imagem em traçados SVG, inspecione as regiões de cor recuperadas e teste uma região no Konva antes de conectar o restante do editor.