SVG no SwiftUI: adicione recursos e controle suas cores

Para um SVG estático incluído no aplicativo SwiftUI, coloque a arte em um catálogo de recursos do Xcode e carregue a imagem pelo nome do recurso. Depois, decida se ela deve manter as cores originais ou virar uma silhueta com tonalização. A Apple adicionou recursos de imagem SVG no Xcode 12; suas notas de versão indicam preservação vetorial para destinos de implantação iOS 13, iPadOS 13 e macOS 10.15 ou posteriores.

Esse fluxo de catálogo é diferente de baixar um arquivo SVG enquanto o aplicativo está em execução. Também é diferente de criar um SF Symbol personalizado. Escolha a opção de entrega antes de alterar a arte ou adicionar um pacote de renderizador.

Escolha a opção para esta imagem específica

Um SVG é o arquivo de origem. A maneira como o aplicativo o recebe e usa determina o próximo passo.

Este passo a passo usa a primeira opção. Uma pequena xícara de duas cores facilita perceber dois erros separados: perder a cor coral do vapor e preencher a alça aberta. Nenhum deles exige uma ilustração complicada para diagnosticar.

O guia de preparação de kits de interface aborda o trabalho mais amplo de tornar um conjunto consistente. Aqui, a questão é como um SVG aceito chega a um Image do SwiftUI.

Prepare um arquivo original pequeno com verificações visíveis

Salve este exemplo original como CupMark.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
  <path d="M12 26H43V45Q43 54 34 54H21Q12 54 12 45Z"
    fill="#147D73"/>
  <path d="M43 30H48Q55 30 55 37Q55 44 48 44H43"
    fill="none" stroke="#147D73" stroke-width="5"/>
  <path d="M24 19Q18 14 25 8M35 19Q29 14 36 8"
    fill="none" stroke="#EB8067" stroke-width="4" stroke-linecap="round"/>
</svg>

A xícara é verde-azulada, os dois contornos de vapor são corais e a área dentro da alça está vazia. Mantenha essas três propriedades na sua lista de revisão. O SVG não contém texto, imagem externa, filtro nem script, portanto oferece um arquivo inicial compacto para um experimento de catálogo.

Para sua arte, inspecione o arquivo original antes de importar. Uma tela vazia excessiva faz um ícone parecer pequeno mesmo quando sua visualização tem as dimensões corretas. Um retângulo branco de fundo se torna parte de uma silhueta template. Uma fotografia incorporada continua sendo um tipo de conteúdo diferente dos traçados ao redor; a verificação de raster incorporado ajuda a diferenciá-los.

Mantenha o mestre editável fora da cópia de entrega do aplicativo. Se o ícone contém letras, resolva a fonte pretendida ou a estratégia de contornos no mestre; veja o fluxo de mudança de fontes SVG. Mudar um estilo de texto SwiftUI não substitui conferir as letras dentro de uma imagem.

Adicione-a como um conjunto comum de imagens

Abra o catálogo de recursos do aplicativo, normalmente Assets.xcassets. Adicione um novo conjunto de imagens e dê a ele o nome CupMark. Arraste o SVG para o campo de imagem adequado. O guia de catálogos de recursos da Apple descreve a criação de conjuntos, a importação de recursos e o fornecimento de variações pelo inspetor Attributes.

Use um conjunto de imagens neste exemplo. Não selecione um fluxo de imagem de símbolo apenas porque o arquivo original termina em .svg.

Após a importação, confira a prévia do catálogo e quaisquer diagnósticos de build. Confirme que o catálogo pertence ao target do aplicativo que o usará. Se sua configuração de recursos contém variações de plataforma ou aparência, certifique-se de que a imagem pretendida está presente na configuração relevante, em vez de supor que a prévia representa todas as configurações.

O nome CupMark é o nome do recurso de imagem usado abaixo. Ele não é uma URL de download nem um caminho para o SVG original na pasta de desenho. O inicializador de Image da Apple busca um recurso pelo nome em um bundle; o padrão é o bundle principal. Se sua imagem pertence a outro bundle de recursos, forneça-o deliberadamente.

Preserve a distinção entre nome de arquivo e nome de recurso nas notas de entrega. Um colega pode renomear o conjunto de recursos sem alterar o nome original do arquivo de desenho, e o código precisa acompanhar o nome do recurso que realmente carrega.

Compare a renderização original e template

Use esta visualização depois de adicionar o conjunto de imagens CupMark:

import SwiftUI
 
struct CupComparison: View {
    var body: some View {
        HStack(spacing: 24) {
            Image("CupMark")
                .renderingMode(.original)
                .resizable()
                .scaledToFit()
                .frame(width: 48, height: 48)
                .accessibilityLabel("Cup with rising steam")
 
            Image("CupMark")
                .renderingMode(.template)
                .resizable()
                .scaledToFit()
                .frame(width: 48, height: 48)
                .foregroundStyle(Color.blue)
                .accessibilityLabel("Cup with rising steam")
        }
        .padding()
    }
}

A instância esquerda solicita explicitamente a renderização original. A instância direita solicita renderização template e fornece azul como estilo de primeiro plano. A documentação de renderização template da Apple define esse modo como pixels não transparentes assumindo a cor de primeiro plano. É um tratamento de silhueta, não um comando para recolorir apenas um traçado SVG.

Para a xícara, isso significa que a versão direita deve ter vapor azul e xícara azul. A distinção coral e verde-azulado desaparece intencionalmente. A abertura da alça deve continuar vazia. Se o aplicativo precisa que o vapor mude de forma independente da xícara, escolha uma estrutura de entrega que exponha essas partes separadamente, em vez de esperar que uma imagem template forneça estilos por traçado.

Os modificadores também tornam explícita a decisão de tamanho. resizable() ativa o comportamento de redimensionamento da imagem, e scaledToFit() preserva sua proporção dentro do quadro de 48 pontos. Um quadro de visualização e a tela da própria arte são limites separados: espaço vazio extra dentro do SVG ainda faz parte do arquivo original.

Este é um exemplo baseado na documentação para experimentar no projeto, não um teste relatado de renderização nativa. Confira o aplicativo realmente compilado, incluindo o menor tamanho em que você pretende usar a marca. Uma prévia clara de 48 pontos não comprova que os dois contornos de vapor continuarão úteis em 16 pontos.

Diagnostique o resultado visível antes de alterar o arquivo

Uma imagem ausente, uma cor alterada e uma silhueta ruim em tamanho pequeno exigem correções diferentes.

Altere uma camada por vez. Se o arquivo original já tem a abertura correta, refazer a vetorização não corrige um nome de recurso digitado errado. Se a busca funciona, mas o modo template remove distinções de cor, adicionar mais cores ao SVG não muda o modo de renderização selecionado.

Para um ícone ao lado de texto visível, revise seu nome acessível no contexto completo do controle. O exemplo fornece uma descrição para cada imagem de comparação. Uma repetição decorativa ao lado de um controle já nomeado pode precisar de outro tratamento de acessibilidade; não aplique mecanicamente os rótulos da visualização de comparação em todos os usos.

Mantenha SVG em tempo de execução e SF Symbols como decisões separadas

Uma imagem nomeada de catálogo não é uma API para buscar e interpretar XML SVG arbitrário. Se o arquivo chega após o build do aplicativo, escolha um renderizador que trate explicitamente essa entrada. Por exemplo, o README do projeto SVGView descreve um interpretador e renderizador SVG escrito em SwiftUI. Avalie os recursos SVG realmente usados pelos seus arquivos; o objetivo de suporte amplo de um pacote não comprova que todo seu conjunto de entradas é renderizado corretamente.

Mantenha o carregamento, as falhas e o comportamento para arquivos incompatíveis como parte desse recurso de tempo de execução. Não adicione um pacote apenas porque uma resposta antiga diz que SwiftUI não pode usar imagens SVG, quando sua necessidade é uma imagem estática já coberta pela opção de catálogo de recursos.

SF Symbols personalizados têm outros requisitos para o arquivo original. A Apple documenta um fluxo de criação e validação baseado em modelos, incluindo variantes de símbolos e informações de alinhamento. Um SVG comum de xícara não adquire essas propriedades ao ser colocado em um conjunto de imagens. Use esse fluxo quando o aplicativo precisar de comportamento de símbolo e mantenha a estrutura exigida pelo modelo.

Vale conferir os formatos de entrega de cada plataforma de forma independente. Se a mesma arte também vai para Android, siga o guia de entrega de VectorDrawable; a aceitação pelo importador de uma plataforma não comprova a aceitação por outra.

Quando seu ícone existe apenas como PNG

Se o arquivo original editável está ausente e o PNG é um ícone simples, o conversor de PNG para SVG do PerfectVector pode ajudar a preparar uma versão candidata da arte para esse fluxo. Recorte até o ícone, inspecione a prévia em busca de aberturas perdidas, detalhes unidos e formas de fundo indesejadas e compare-a com o original. Baixe o SVG aceito e teste-o pelas mesmas verificações de conjunto de imagens e modo de renderização.

Use o vetor original quando ele existe. Mantenha fotografias e imagens com muitos efeitos como raster quando isso preserva melhor sua aparência. A vetorização prepara geometria; ela não compila o catálogo do Xcode, não escolhe seu bundle de recursos nem produz um modelo de SF Symbols com as variantes exigidas.

Antes de entregar o recurso, registre seu nome no catálogo, comportamento original ou template pretendido, tamanho visual mínimo e arquivo de origem usado para regenerá-lo. Teste fundos claros e escuros e quaisquer variações de aparência compatíveis no aplicativo. Os guias de arte do blog abordam a preparação da arte original que vem antes dessa etapa de entrega.

Perguntas frequentes

O SwiftUI pode usar um SVG de um catálogo de recursos? Sim. O Xcode oferece suporte a recursos de imagem SVG. Adicione o arquivo a um conjunto comum de imagens e carregue o recurso nomeado com Image. Verifique o destino de implantação e o build real do catálogo, em vez de tratar isso como suporte a arquivos SVG arbitrários em tempo de execução.

Por que meu SVG ficou de uma só cor? Confira o modo de renderização. A renderização template usa a imagem visível como uma silhueta na cor de primeiro plano. Use a renderização original quando precisar das distinções originais de cor da arte.

Image pode carregar um SVG de uma URL web? O inicializador nomeado de Image é uma busca de recurso, não um interpretador SVG baseado em URL. Arquivos SVG em tempo de execução exigem um fluxo adequado de renderização e carregamento, verificado com suas entradas reais.

Um conjunto de imagens SVG é a mesma coisa que um SF Symbol personalizado? Não. Símbolos personalizados usam um modelo com estrutura necessária, variantes, informações de alinhamento e validação. Um conjunto normal de imagens SVG não fornece automaticamente essas propriedades de símbolo.

Fontes

1. Apple — notas de versão do Xcode 12 — Suporte a recursos de imagem SVG e destinos documentados de implantação com preservação vetorial.
2. Apple — gerenciamento de recursos com catálogos — Conjuntos de recursos, campos de importação e variações.
3. Apple — Image init(_:bundle:) — Busca de recurso nomeado e bundle.
4. Apple — Image.TemplateRenderingMode — Modos de renderização original e template.
5. Apple — resizable(capInsets:resizingMode:) — Comportamento explícito de redimensionamento da imagem.
6. Apple — scaledToFit() — Ajuste preservando a proporção.
7. Apple — criação de imagens de símbolos personalizados para seu app — Modelos de símbolos personalizados, variantes e validação.
8. Exyte — SVGView — Uma solução separada de interpretação e renderização SVG para SwiftUI.

Confira um ícone no tamanho e modo de cor pretendidos antes de importar o conjunto. Se resta apenas um PNG, prepare uma versão candidata em SVG, inspecione suas aberturas e fundo e verifique o arquivo aceito no aplicativo compilado.