SVG no .NET MAUI: mantenha o SVG e referencie o PNG

Para usar SVG no fluxo de imagens empacotadas do .NET MAUI, mantenha o SVG no projeto e referencie seu nome PNG gerado em XAML ou C#. O MAUI processa a origem vetorial durante o build. Um Image que aponta para compass.png pode, portanto, estar correto mesmo quando o arquivo adicionado é compass.svg. O guia de imagens do projeto da Microsoft documenta essa conversão.

Isso explica o nome do arquivo, mas deixa uma questão de desenho: que tamanho o MAUI deve gerar e o que você deve inspecionar depois? Acompanhe um pequeno emblema de bússola pela origem, pelos metadados do projeto e pela declaração de exibição.

Acompanhe o arquivo original pelo build

O SVG editável e a imagem empacotada têm funções diferentes. Mantenha o SVG original para poder ajustar suas formas, espaços vazios ou cores depois. Use o nome gerado na visualização que exibe a imagem.

A documentação do controle Image descreve as imagens para densidades de destino entrando no pacote do aplicativo e o sistema operacional selecionando uma resolução adequada. Manter um mestre SVG não significa que esse fluxo específico entrega um documento SVG ativo à visualização.

Adicione um pequeno SVG com limites claros

Salve este exemplo original como Resources/Images/compass.svg:

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

O anel deixa um centro transparente, e o ponteiro coral é uma forma separada. Esses detalhes dão a você algo específico para conferir após a importação. As dimensões declaradas e o viewBox quadrado também deixam claro o enquadramento pretendido. Consulte o guia de arquivos SVG para entender como a geometria vetorial difere de um bitmap incorporado em um invólucro SVG.

No projeto, confirme que o arquivo tem a ação de build MauiImage. A Microsoft documenta a pasta Resources/Images como o local normal. Antes de adicionar XML, inspecione os itens existentes do projeto: seu projeto pode já incluir essa pasta com um curinga. A configuração de imagens do projeto explica o local e a ação de build.

Atualize um item existente uma única vez

Se um curinga MauiImage existente já inclui o arquivo da bússola, coloque esta atualização de metadados depois dessa inclusão:

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Update altera os metadados de um item que já existe. Ele não adiciona um arquivo ausente à lista de itens. Se seu projeto não tem uma inclusão correspondente, adicione o arquivo uma vez com a ação de build MauiImage ou um Include explícito. A referência de Item do MSBuild da Microsoft diferencia essas operações.

Isso evita um reparo tentador: adicionar repetidamente entradas Include enquanto investiga uma imagem ausente. Primeiro estabeleça se o arquivo está incluído e depois altere seus metadados.

Referencie o PNG e defina a área de exibição

Coloque esta declaração dentro de uma página ou layout MAUI existente:

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

A extensão .png é intencional. A largura e a altura solicitam uma área de exibição quadrada; AspectFit mantém a imagem inteira visível dentro dela. Se sua ilustração é retangular, use uma área de exibição adequada a ela, em vez de esticá-la para preencher um quadrado. A referência de escala de Image da Microsoft diferencia ajuste, recorte e esticamento.

O código da bússola é um exemplo original de configuração, não um teste registrado de renderização em dispositivo. Compile-o no seu próprio projeto de destino e inspecione a visualização resultante. Um nome de arquivo correto, sozinho, não comprova que sua arte específica é renderizada como pretendido.

BaseSize e tamanho de layout resolvem problemas diferentes

BaseSize="48,48" fornece as dimensões de base das quais o MAUI deriva imagens específicas para cada densidade. Sem um tamanho base explícito, o MAUI usa as dimensões do próprio SVG. A Microsoft documenta as duas regras em redimensionar uma imagem.

Neste exemplo, o desenho de origem usa um espaço de coordenadas de 96 por 96, enquanto a base solicitada e a visualização têm 48 por 48. Esses números são escolhas deliberadas de criação, não dimensões de saída medidas em um build. O anel deve manter suas proporções quando escalado.

Se você depois usar o mesmo emblema em uma visualização muito maior, reveja o tamanho do build e inspecione esse uso também. Alterar WidthRequest não edita a arte de origem nem seus metadados de build. Por outro lado, alterar BaseSize não remove margens vazias dentro do SVG. Aproxime os limites do desenho da arte no arquivo original se o próprio emblema parecer pequeno demais dentro de uma visualização com tamanho correto.

Evite usar Resize="false" como correção geral de nitidez. Ele desativa o redimensionamento de imagens vetoriais nesse fluxo. Escolha-o somente quando esse for o comportamento pretendido, seguindo a opção de redimensionamento documentada.

Confira em ordem uma imagem ausente ou inesperada

1. Confirme o nome do arquivo e o item do projeto. Use um nome em minúsculas, como compass.svg, e confira se há outra imagem com o mesmo nome. As regras de nomenclatura da Microsoft exigem nomes únicos de imagem e caracteres compatíveis com Android.
2. Confira a origem da visualização. Para o fluxo de SVG empacotado, use compass.png em XAML ou C#.
3. Compare a área de exibição pretendida com o tamanho base. Uma mudança de tamanho da visualização e uma mudança de tamanho do build pertencem a lugares diferentes.
4. Inspecione a própria arte. O centro do anel ainda está aberto? O ponteiro coral é distinto? O emblema está centralizado ou um espaço vazio invisível no arquivo original o desloca?

Inspecione também metadados de imagem que alteram a pintura. O guia de imagens do projeto documenta TintColor e Color para tonalização e cor de fundo. Deixe-os sem definição neste exemplo de duas cores, a menos que você pretenda alterar sua aparência. Confira a imagem contra o fundo real da página, onde é mais fácil perceber a perda de uma abertura transparente.

Quando você precisa de comportamento SVG em tempo de execução

Conteúdo SVG baixado, traçados interativos ou edições em tempo de execução precisam de uma decisão separada de implementação. As instruções de imagens empacotadas acima não demonstram suporte a esses trabalhos.

Por exemplo, o projeto de amostras SVG do Vapolia documenta seus próprios controles SvgImage e SvgImageSource e a configuração de recursos incorporados. Esse é outro contrato de carregamento. Avalie os recursos compatíveis e as plataformas de destino do renderizador com seu arquivo real antes de introduzi-lo; trocar a extensão do nome de arquivo em uma declaração comum de Image não instala um renderizador.

A mesma arte também precisa de outra configuração no fluxo de imagens SVG do Flutter, no catálogo de recursos do SwiftUI e na importação de VectorDrawable do Android. Reutilize o mestre de origem e siga as regras de cada destino.

Prepare um mestre vetorial quando resta apenas um PNG

Se a bússola ou logo existe apenas como PNG, o PerfectVector pode ajudar a criar uma arte SVG editável antes de adicioná-la ao projeto MAUI. Converta o PNG para SVG e inspecione a abertura do anel, as pequenas partes separadas e o espaçamento em um editor. Mantenha um mestre limpo para mudanças posteriores de tamanho ou cor.

A vetorização não repara uma declaração MauiImage nem transforma o fluxo de imagens empacotadas em um interpretador SVG de tempo de execução. Se o arquivo original já é um SVG editável, trabalhe diretamente na configuração do projeto ou no desenho. Fotos e artes texturizadas podem ser mais úteis como imagens raster; vetorizá-las apenas porque o aplicativo aceita origens SVG acrescenta uma decisão separada sobre a arte.

Perguntas frequentes

Por que referencio um PNG quando adicionei um SVG? O .NET MAUI converte origens de imagem SVG empacotadas para PNG durante o build. Mantenha o SVG no projeto e referencie o nome de arquivo PNG em XAML ou C#.

BaseSize define o tamanho do controle Image? BaseSize define as dimensões de base usadas para derivar imagens de build específicas para cada densidade. O layout e as solicitações de tamanho da visualização controlam sua área de exibição.

Devo adicionar outro MauiImage Include para alterar BaseSize? Confira se o arquivo já está incluído, inclusive por um curinga. Use Update para alterar os metadados de um item existente; use Include somente quando o item precisar ser adicionado.

Isso carregará um SVG baixado depois do build do aplicativo? O fluxo de imagens empacotadas não cobre baixar e interpretar SVG em tempo de execução. Escolha e teste uma abordagem de renderização em tempo de execução para essa necessidade.

Fontes

1. Microsoft — adicionar imagens a um projeto de aplicativo .NET MAUI — Processamento de SVG para PNG, itens de imagem, nomes de arquivo, tamanho base e metadados de build.
2. Microsoft — Image — Referências de imagens locais, seleção de densidade de destino, dimensionamento da visualização e comportamento de escala.
3. Microsoft — elemento Item (MSBuild) — Diferença entre adicionar um item com Include e alterar metadados existentes com Update.
4. Vapolia — amostras SVG — Um controle SVG separado de tempo de execução e fluxo de carregamento de recursos.

Você está trabalhando com um emblema de aplicativo disponível somente em raster? Transforme seu PNG em um SVG editável, confira suas aberturas e seu espaçamento, adicione esse mestre ao MAUI e inspecione a imagem gerada no aplicativo de destino.