SVG in .NET MAUI: conserva l'SVG, usa il nome PNG

Per usare SVG nel procedimento delle immagini incluse di .NET MAUI, conserva l'SVG nel progetto e fai riferimento in XAML o C# al nome PNG generato. MAUI elabora la sorgente vettoriale durante la build. Un Image che punta a compass.png può quindi essere corretto anche quando il file aggiunto è compass.svg. La guida Microsoft alle immagini di progetto documenta questa conversione.

Questo spiega il nome del file, ma lascia una domanda di progettazione: quali dimensioni deve generare MAUI e cosa devi esaminare dopo? Segui un piccolo emblema a bussola attraverso sorgente, metadati del progetto e dichiarazione di visualizzazione.

Segui la sorgente attraverso la build

L'SVG modificabile e l'immagine nel pacchetto hanno compiti diversi. Conserva la sorgente per regolare in seguito forme, spazi vuoti o colori. Usa il nome generato nella vista che la visualizza.

La documentazione del controllo Image descrive le immagini alle densità di destinazione che entrano nel pacchetto dell'app e la scelta della risoluzione appropriata da parte del sistema operativo. Conservare un originale SVG non significa che questo specifico procedimento consegni un documento SVG attivo alla vista.

Aggiungi un piccolo SVG con limiti chiari

Salva questo esempio originale come 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>

L'anello lascia un centro trasparente e l'ago corallo è una forma separata. Quei dettagli offrono elementi specifici da controllare dopo l'importazione. Le dimensioni dichiarate e il viewBox quadrato rendono chiara anche l'inquadratura prevista. Consulta la guida ai file SVG per capire come la geometria vettoriale differisce da una bitmap incorporata in un contenitore SVG.

Nel progetto, conferma che il file abbia l'azione di build MauiImage. Microsoft documenta la cartella Resources/Images come posizione normale. Prima di aggiungere XML, esamina gli elementi di progetto esistenti: il progetto può già includere quella cartella con un carattere jolly. La configurazione delle immagini di progetto spiega posizione e azione di build.

Aggiorna una sola volta un elemento esistente

Se un carattere jolly MauiImage esistente include già il file della bussola, inserisci questo aggiornamento dei metadati dopo quell'inclusione:

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

Update cambia i metadati di un elemento già esistente. Non aggiunge un file assente all'elenco degli elementi. Se il progetto non ha un'inclusione corrispondente, aggiungi il file una volta con l'azione di build MauiImage oppure un Include esplicito. La documentazione Microsoft di Item in MSBuild distingue queste operazioni.

Questo evita una correzione allettante: aggiungere ripetutamente voci Include durante la diagnosi di un'immagine assente. Stabilisci prima se il file è incluso, poi cambia i suoi metadati.

Fai riferimento al PNG e imposta l'area di visualizzazione

Inserisci questa dichiarazione dentro una pagina o un layout MAUI esistenti:

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

L'estensione .png è voluta. Larghezza e altezza richiedono un'area di visualizzazione quadrata; AspectFit mantiene l'intera immagine visibile al suo interno. Se l'illustrazione è rettangolare, usa un'area di visualizzazione adatta anziché deformarla per riempire un quadrato. La documentazione Microsoft del ridimensionamento delle immagini distingue adattamento, ritaglio e deformazione.

Il codice della bussola è un esempio originale di configurazione, non un test registrato di rendering su dispositivo. Esegui la build nel tuo progetto di destinazione ed esamina la vista risultante. Un nome di file corretto da solo non dimostra che la tua specifica grafica venga renderizzata come previsto.

BaseSize e dimensioni del layout risolvono problemi diversi

BaseSize="48,48" fornisce le dimensioni di base da cui MAUI ricava immagini specifiche per densità. Senza dimensioni di base esplicite, MAUI usa quelle proprie dell'SVG. Microsoft documenta entrambe le regole in Ridimensionare un'immagine.

In questo esempio il disegno sorgente usa uno spazio di coordinate di 96 per 96, mentre la base richiesta e la vista sono 48 per 48. Quei numeri sono scelte deliberate dell'autore, non dimensioni di uscita misurate da una build. L'anello dovrebbe mantenere le proporzioni quando scalato.

Se in seguito usi lo stesso emblema in una vista molto più grande, rivedi le dimensioni di build ed esamina anche quell'uso. Cambiare WidthRequest non modifica la grafica sorgente o i metadati di build. Viceversa, cambiare BaseSize non rimuove i margini vuoti nell'SVG. Restringi i limiti del disegno nella sorgente se l'emblema appare troppo piccolo dentro una vista altrimenti delle dimensioni corrette.

Evita di usare Resize="false" come correzione generale della nitidezza. Disabilita il ridimensionamento delle immagini vettoriali in questo procedimento. Sceglilo soltanto quando è il comportamento desiderato, seguendo l'opzione di ridimensionamento documentata.

Controlla in ordine un'immagine assente o inattesa

1. Conferma nome del file ed elemento di progetto. Usa un nome minuscolo come compass.svg e controlla che non esista un'altra immagine con lo stesso nome. Le regole di denominazione di Microsoft richiedono nomi di immagine univoci e caratteri compatibili con Android.
2. Controlla la sorgente della vista. Per il procedimento degli SVG inclusi, usa compass.png in XAML o C#.
3. Confronta l'area di visualizzazione prevista con le dimensioni di base. Un cambiamento delle dimensioni della vista e uno delle dimensioni di build appartengono a punti diversi.
4. Esamina la grafica stessa. Il centro dell'anello è ancora aperto? L'ago corallo è distinto? L'emblema è centrato oppure spazi vuoti invisibili della sorgente lo spostano di lato?

Esamina anche gli eventuali metadati immagine che cambiano i colori. La guida alle immagini di progetto documenta TintColor e Color per tinta e colore di sfondo. Lasciali non impostati per questo esempio a due colori, a meno che tu voglia cambiarne l'aspetto. Controlla l'immagine sullo sfondo effettivo della pagina, dove è più facile notare un'apertura trasparente persa.

Quando serve il comportamento SVG in esecuzione

Contenuto SVG scaricato, tracciati interattivi o modifiche durante l'esecuzione richiedono una decisione di implementazione separata. Le istruzioni sulle immagini incluse sopra non dimostrano supporto per quei compiti.

Per esempio, il progetto di esempi SVG Vapolia documenta i propri controlli SvgImage e SvgImageSource e la configurazione delle risorse incorporate. È un contratto di caricamento diverso. Valuta funzioni supportate e piattaforme di destinazione del renderer usando il tuo file effettivo prima di introdurlo; cambiare l'estensione del file in una normale dichiarazione Image non installa un renderer.

La stessa grafica richiede anche configurazioni diverse nel procedimento di immagini SVG Flutter, nel catalogo delle risorse SwiftUI e in un'importazione Android VectorDrawable. Riutilizza l'originale sorgente, poi segui le regole di ogni destinazione.

Prepara un originale vettoriale quando resta soltanto un PNG

Se la bussola o il logo esiste soltanto come PNG, PerfectVector può aiutare a creare grafica SVG modificabile prima di aggiungerla al progetto MAUI. Converti il PNG in SVG, poi esamina apertura dell'anello, piccole parti staccate e spaziatura in un editor. Conserva un originale pulito per cambiamenti successivi di dimensioni o colori.

La vettorializzazione non corregge una dichiarazione MauiImage e non trasforma il procedimento delle immagini incluse in un parser SVG durante l'esecuzione. Se la sorgente è già un SVG modificabile, lavora direttamente sulla configurazione del progetto o sul disegno. Fotografie e grafica con texture possono essere più utili come immagini raster; ricalcarle soltanto perché l'app accetta sorgenti SVG aggiunge una decisione grafica separata.

FAQ

Perché faccio riferimento a un PNG quando ho aggiunto un SVG? .NET MAUI converte le sorgenti immagine SVG incluse in PNG durante la build. Conserva l'SVG nel progetto e fai riferimento al nome PNG in XAML o C#.

BaseSize imposta le dimensioni del controllo Image? BaseSize imposta le dimensioni di base usate per ricavare immagini di build specifiche per densità. Layout e richieste di dimensioni della vista controllano la sua area di visualizzazione.

Dovrei aggiungere un altro MauiImage Include per cambiare BaseSize? Controlla se il file è già incluso, anche tramite un carattere jolly. Usa Update per cambiare i metadati di un elemento esistente; usa Include soltanto quando l'elemento deve essere aggiunto.

Questo caricherà un SVG scaricato dopo la build dell'app? Il procedimento delle immagini incluse non copre il download e parsing SVG durante l'esecuzione. Scegli e testa un approccio di rendering durante l'esecuzione per quel requisito.

Fonti

1. Microsoft — Aggiungere immagini a un progetto di app .NET MAUI — Elaborazione da SVG a PNG, elementi immagine, nomi dei file, dimensioni di base e metadati di build.
2. Microsoft — Image — Riferimenti a immagini locali, selezione della densità di destinazione, dimensioni della vista e comportamento di ridimensionamento.
3. Microsoft — Elemento Item (MSBuild) — Differenza tra aggiungere un elemento con Include e cambiare metadati esistenti con Update.
4. Vapolia — Esempi SVG — Un distinto controllo SVG durante l'esecuzione e procedimento di caricamento delle risorse.

Lavori da un emblema app soltanto raster? Trasforma il PNG in un SVG modificabile, controlla aperture e spaziatura, poi aggiungi quell'originale a MAUI ed esamina l'immagine generata nella tua app di destinazione.