Imagens SVG no Flutter: empacote, dimensione e confira os recursos

Para exibir um recurso SVG no Flutter, adicione flutter_svg, declare o arquivo em pubspec.yaml e carregue esse mesmo caminho com SvgPicture.asset. Dê dimensões ou restrições adequadas de layout ao widget e inspecione a arte no aplicativo. O construtor de recurso do pacote documenta essa opção de carregamento.

Mantenha duas perguntas separadas: o aplicativo carregou o arquivo pretendido, e o renderizador reproduziu a arte pretendida? Exportar novamente um desenho não repara uma chave de recurso digitada errada. Corrigir a chave não simplifica um efeito incompatível.

Este passo a passo usa uma ilustração original de colinas e sol para tornar essas verificações fáceis de administrar. O código segue a API documentada; não é um relato de teste de aplicativo compilado.

Comece com um arquivo original pequeno que você consiga inspecionar

Crie assets/illustrations/hills.svg no projeto Flutter:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 48">
  <circle cx="49" cy="11" r="6" fill="#e99b30"/>
  <path d="M4 42L24 14L44 42Z" fill="#167d8d"/>
  <path d="M28 42L43 23L60 42Z" fill="#233b63"/>
</svg>

O arquivo original tem duas colinas triangulares sobrepostas e um sol âmbar separado. Ele usa preenchimentos explícitos, não tem texto nem imagens vinculadas e deixa um espaço visível entre o sol e as colinas. Esses detalhes oferecem uma lista curta de aceitação ao conferir o aplicativo.

Mantenha uma cópia desse arquivo simples ao introduzir sua própria arte depois. Se o arquivo original pequeno funciona, mas a substituta falha, compare suas estruturas antes de alterar toda a configuração de carregamento.

Um recurso SVG do Flutter também é uma opção de entrega diferente de XML VectorDrawable do Android. Se seu destino é um drawable Android nativo, use o guia de preparação de VectorDrawable para Android, em vez de tratar os dois formatos como intercambiáveis.

Adicione o pacote e declare o arquivo exato

Na raiz do projeto Flutter, use o comando oficial de instalação:

flutter pub add flutter_svg

Depois, adicione esta entrada de recurso na seção flutter: existente de pubspec.yaml:

flutter:
  assets:
    - assets/illustrations/hills.svg

Mescle a entrada na configuração atual, em vez de criar uma segunda seção flutter:. Mantenha a indentação mostrada. A documentação de recursos do Flutter define esses caminhos em relação a pubspec.yaml e explica como os arquivos listados entram no pacote do aplicativo.

Use a mesma grafia, capitalização e estrutura de diretórios no nome de arquivo, declaração e chamada Dart. Para essa primeira verificação, uma entrada explícita de arquivo é mais fácil de comparar que uma entrada ampla de pasta. Se você depois declarar diretórios, o Flutter documenta que uma entrada de diretório cobre seus arquivos diretos; diretórios aninhados precisam de suas próprias entradas.

Depois de mudar a configuração de recursos, recompile e execute o aplicativo com seu fluxo normal de desenvolvimento. Não suponha que um arquivo visível no editor já está incluído no aplicativo que você está vendo.

Carregue a arte em uma caixa definida

Adicione estas importações ao arquivo Dart que contém seu widget:

import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

Coloque este widget em uma parte adequada da tela:

SvgPicture.asset(
  'assets/illustrations/hills.svg',
  width: 128,
  height: 96,
  fit: BoxFit.contain,
  semanticsLabel: 'Sun above two hills',
  errorBuilder: (context, error, stackTrace) =>
      const Text('Illustration unavailable'),
)

A caixa acompanha as proporções da arte original. Inspecione o sol separado, as cores das duas colinas e as margens externas antes de experimentar um tamanho menor. Depois, use as dimensões exigidas pelo componente real; os números acima são um exemplo, não um tamanho mínimo nem uma recomendação de desempenho.

A documentação do construtor recomenda dimensões explícitas ou restrições estritas de layout para que o carregamento não altere inesperadamente o layout. Se a arte parece pequena demais na caixa, inspecione o espaço vazio de seu viewBox e as dimensões do widget.

O rótulo descreve o propósito desta imagem independente. A API semanticsLabel o conecta ao rótulo semântico da imagem. Para uma imagem decorativa ao lado de texto que já comunica o significado, considere excluí-la da semântica. A opção excludeFromSemantics do construtor tem prioridade sobre seu rótulo. Revise o significado falado do componente inteiro, em vez de rotular cada forma separadamente.

Diferencie um marcador de carregamento de um erro

Um indicador de carregamento não comprova que um SVG foi aceito. O pacote fornece placeholderBuilder para o período de obtenção ou decodificação, enquanto a API atual de errorBuilder fornece um widget quando o carregamento da imagem falha.

O exemplo acima usa um pequeno texto como alternativa. Durante o desenvolvimento, mude deliberadamente o caminho Dart para um nome de arquivo inexistente e confira se você consegue reconhecer a falha. Restaure o caminho correto antes de continuar. Isso testa sua apresentação de falha sem mudar o próprio desenho.

Depois, teste seu arquivo original real. Se ele ainda falha, inspecione a saída de diagnóstico e compare primeiro o caminho declarado. Um exemplo de rede que exibe outro SVG não demonstra que seu arquivo local está empacotado nem que seus recursos são compatíveis.

Decida entre preservar a paleta e aplicar uma tonalização

Deixe colorFilter sem definição quando as colinas precisam continuar uma verde-azulada e a outra azul-marinho com um sol âmbar. Para um tratamento deliberado de uma só cor, adicione um filtro como:

colorFilter: const ColorFilter.mode(
  Color(0xFF175CD3),
  BlendMode.srcIn,
),

O pacote documenta esse padrão de tonalização. A referência de BlendMode do Flutter explica que srcIn usa a opacidade do destino e ignora seus canais de cor. Uma tonalização uniforme, portanto, remove a distinção da paleta original; é uma escolha de desenho, não um reparo de preservação de cor.

Para as colinas, confira se perder o contraste entre os dois triângulos sobrepostos torna a ilustração mais difícil de ler. Mantenha a paleta original se essas regiões precisam continuar distintas. O pacote também documenta ColorMapper para substituições seletivas, mas comece com o caso mais simples, sem filtro, ao diagnosticar uma diferença.

Simplifique os recursos somente depois que o arquivo carregar

A documentação de flutter_svg recomenda atributos de apresentação ao exportar do Illustrator porque o suporte a CSS é incompleto, e imagens incorporadas em vez de vinculadas externamente. Ela também fornece uma verificação de compatibilidade baseada em compilador. Siga essa verificação no seu ambiente Flutter/Dart quando um recurso complexo precisar de investigação.

Uma prévia no navegador é uma referência útil da aparência pretendida; não comprova que todos os recursos SVG serão renderizados de maneira idêntica pelo pacote. Mantenha a arte original e simplifique uma cópia, uma mudança por vez.

Se a arte original contém letras, decida se elas devem continuar como texto do aplicativo ou arte fixa. O guia de mudanças de fonte SVG explica por que a aparência pode depender do tratamento de texto e fontes. Não vetorize um rótulo apenas para resolver um problema de caminho de recurso.

Para uma família de recursos de interface, compare seus tamanhos visuais e espaçamentos em conjunto. O guia de preparação de ícones para kits de interface ajuda nessa verificação de consistência.

Use a vetorização quando a imagem original precisar de recuperação

Mantenha um SVG limpo existente. Uma fotografia ou fundo texturizado pode ser melhor entregue como um recurso raster adequado; alterar a extensão não o torna geometria vetorial útil.

Se uma ilustração simples existe apenas como um PNG irregular, o fluxo de PNG para SVG do PerfectVector pode ajudar a preparar uma versão candidata editável. Recorte até a arte, inspecione a prévia em busca de formas ausentes e regiões de fundo indesejadas e baixe o SVG. Adicione esse arquivo ao pacote do aplicativo e repita as verificações de carregamento, paleta, tamanho e semântica.

Para o exemplo das colinas, procure o sol separado e a separação entre as duas encostas coloridas. Confirme que o arquivo contém a estrutura pretendida; o guia de raster incorporado explica por que um invólucro SVG ainda pode conter pixels.

Avalie o recurso no aplicativo antes de escolher uma estratégia de otimização. Este fluxo não faz nenhuma promessa geral de que SVG é menor ou mais rápido que PNG.

Se reutilizar a arte em um aplicativo .NET MAUI, siga o fluxo MAUI de SVG original para PNG. O projeto mantém o mestre SVG, enquanto a visualização referencia um PNG preparado durante o build.

Perguntas frequentes

Como adiciono uma imagem SVG ao Flutter? Adicione flutter_svg, declare o recurso SVG em pubspec.yaml e carregue o caminho correspondente com SvgPicture.asset. Defina dimensões ou restrições adequadas e inspecione o resultado.

Por que meu SVG local não aparece? Confira primeiro a declaração do recurso, o caminho exato, o erro de carregamento e o layout. Se um arquivo original simples funciona, compare a estrutura e os recursos compatíveis da arte que falha.

Por que todas as cores ficaram iguais? Um filtro uniforme de cor srcIn substitui a paleta visível por sua tonalização. Remova esse filtro quando as cores originais devem continuar distintas.

Preciso transformar PNG em SVG para o Flutter? Não. Use um recurso raster adequado quando ele atende à arte. A vetorização é opcional ao recuperar formas editáveis de uma imagem raster original simples.

Fontes

1. flutter_svg — instalação — Instalação do pacote e importação Dart.
2. Flutter — adição de recursos e imagens — Declarações de recursos, caminhos e empacotamento.
3. flutter_svg — SvgPicture.asset — Carregamento de recursos, dimensões, ajuste e controles de semântica.
4. flutter_svg — errorBuilder — Apresentação de falhas distinta de marcadores de carregamento.
5. flutter_svg — semanticsLabel — Propósito semântico da imagem.
6. Flutter — BlendMode — Tratamento de cor srcIn baseado em opacidade.
7. flutter_svg — documentação do pacote — Tonalização, mapeamento seletivo de cores, orientações de exportação e verificações de compatibilidade.

Comece com um recurso declarado e confira seu caminho, paleta, tamanho e significado no aplicativo. Se uma ilustração raster precisa de recuperação, prepare uma versão candidata em SVG, inspecione suas formas e execute as mesmas verificações antes de adicioná-la à família de recursos.