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

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

> Adicione SVG ao Flutter, confira o caminho no pacote, defina dimensões do widget e confira cores e semântica. Separe problemas de carregamento de arte incompatível.

Source: https://perfectvector.com/pt-BR/blog/flutter-svg-images

Language: pt-BR
Author: Irene Kim
Published: 2026-09-13T08:00:00+09:00

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](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) 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
<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.

![Fluxo conceitual de um arquivo SVG de colinas e sol por uma pasta de recursos até a mesma arte dentro de um quadro de exibição](https://perfectvector.com/blog/flutter-svg-images/asset-bundle-widget.webp)

*Ilustração conceitual: arte original, empacotamento do recurso e exibição no widget são pontos de verificação separados.*

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](https://perfectvector.com/pt-BR/blog/convert-png-to-android-vector-drawable), 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](https://pub.dev/packages/flutter_svg/install):

```bash
flutter pub add flutter_svg
```

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

```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](https://docs.flutter.dev/ui/assets/assets-and-images) 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:

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

Coloque este widget em uma parte adequada da tela:

```dart
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](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) 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](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/semanticsLabel.html) 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](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/errorBuilder.html) 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:

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

O pacote documenta esse padrão de tonalização. A [referência de BlendMode do Flutter](https://api.flutter.dev/flutter/dart-ui/BlendMode.html) 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](https://pub.dev/packages/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.

| O que você observa                                 | Próxima comparação                                                      |
| -------------------------------------------------- | ----------------------------------------------------------------------- |
| Nada aparece                                       | Chave do recurso, declaração, alternativa e saída de diagnóstico        |
| As colinas simples aparecem, mas outro desenho não | Estrutura do arquivo original e compatibilidade do renderizador         |
| Todas as regiões ficam de uma só cor               | Filtro de cor do widget antes de editar preenchimentos da arte original |
| O desenho fica minúsculo na caixa                  | Espaço vazio do viewBox e restrições de layout                          |
| O texto muda ou desaparece                         | Dependências de fontes e tratamento pretendido do texto                 |
| Um detalhe está ausente no tamanho do componente   | Geometria original, sobreposições e espaço disponível                   |

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](https://perfectvector.com/pt-BR/blog/svg-font-changes) 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](https://perfectvector.com/pt-BR/blog/convert-png-icons-to-svg-for-ui-kit) 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](https://perfectvector.com/pt-BR/convert-png-to-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](https://perfectvector.com/pt-BR/blog/svg-contains-raster-image) 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](https://perfectvector.com/pt-BR/blog/svg-in-dotnet-maui). 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](https://pub.dev/packages/flutter_svg/install) — Instalação do pacote e importação Dart.
2. [Flutter — adição de recursos e imagens](https://docs.flutter.dev/ui/assets/assets-and-images) — Declarações de recursos, caminhos e empacotamento.
3. [flutter\_svg — SvgPicture.asset](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/SvgPicture.asset.html) — Carregamento de recursos, dimensões, ajuste e controles de semântica.
4. [flutter\_svg — errorBuilder](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/errorBuilder.html) — Apresentação de falhas distinta de marcadores de carregamento.
5. [flutter\_svg — semanticsLabel](https://pub.dev/documentation/flutter_svg/latest/svg/SvgPicture/semanticsLabel.html) — Propósito semântico da imagem.
6. [Flutter — BlendMode](https://api.flutter.dev/flutter/dart-ui/BlendMode.html) — Tratamento de cor srcIn baseado em opacidade.
7. [flutter\_svg — documentação do pacote](https://pub.dev/packages/flutter_svg) — 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](https://perfectvector.com/pt-BR/convert-png-to-svg), inspecione suas formas e execute as mesmas verificações antes de adicioná-la à família de recursos.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/flutter-svg-images)
- [SVG no SwiftUI: adicione recursos e controle suas cores](https://perfectvector.com/pt-BR/blog/svg-in-swiftui.md)
- [SVG no WPF: escolha um renderizador ou desenho XAML](https://perfectvector.com/pt-BR/blog/svg-in-wpf.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
