SVG in .NET MAUI: SVG behalten, PNG referenzieren

Um SVG im Ablauf für mitgelieferte Bilder von .NET MAUI zu verwenden, behalte das SVG im Projekt und referenziere aus XAML oder C# seinen erzeugten PNG-Namen. MAUI verarbeitet die Vektorquelle beim Build. Ein Image, das auf compass.png zeigt, kann also korrekt sein, obwohl du die Datei compass.svg hinzugefügt hast. Microsofts Leitfaden zu Projektbildern dokumentiert diese Konvertierung.

Das erklärt den Dateinamen, lässt aber eine Designfrage offen: Welche Größe soll MAUI erzeugen, und was solltest du danach prüfen? Verfolge ein kleines Kompassemblem durch Quelle, Projektmetadaten und Anzeigedeklaration.

Verfolge die Quelle durch den Build

Das bearbeitbare SVG und das verpackte Bild haben unterschiedliche Aufgaben. Behalte die Quelle, damit du ihre Formen, Leerräume oder Farben später anpassen kannst. Verwende den erzeugten Namen in der Ansicht, die es anzeigt.

Die Dokumentation zum Image-Steuerelement beschreibt die Bilder für Zielpixeldichten im App-Paket und die Auswahl einer passenden Auflösung durch das Betriebssystem. Das Behalten einer SVG-Masterdatei bedeutet nicht, dass dieser konkrete Ablauf ein live gerendertes SVG-Dokument an die Ansicht liefert.

Füge ein kleines SVG mit klaren Grenzen hinzu

Speichere dieses eigene Beispiel als 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>

Der Ring lässt eine transparente Mitte, und die korallfarbene Nadel ist eine separate Form. Diese Details geben dir konkrete Prüfpunkte nach dem Import. Die deklarierten Abmessungen und die quadratische viewBox machen auch den vorgesehenen Rahmen deutlich. Siehe den SVG-Dateileitfaden, um zu erfahren, wie sich Vektorgeometrie von einer in SVG eingebetteten Bitmap unterscheidet.

Bestätige in deinem Projekt, dass die Datei die Buildaktion MauiImage hat. Microsoft dokumentiert Resources/Images als normalen Speicherort. Prüfe vor dem Hinzufügen von XML die vorhandenen Projektelemente: Dein Projekt kann diesen Ordner bereits mit einem Platzhalter einschließen. Die Einrichtung von Projektbildern erklärt Ablage und Buildaktion.

Aktualisiere ein vorhandenes Element einmal

Wenn ein vorhandener MauiImage-Platzhalter die Kompassdatei bereits einschließt, platziere diese Metadatenaktualisierung nach diesem Einschluss:

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

Update ändert Metadaten eines bereits vorhandenen Elements. Es fügt der Elementliste keine fehlende Datei hinzu. Wenn dein Projekt keinen passenden Einschluss hat, füge die Datei stattdessen einmal mit der Buildaktion MauiImage oder einem expliziten Include hinzu. Microsofts MSBuild-Item-Referenz unterscheidet diese Operationen.

Das vermeidet eine verlockende Reparatur: während der Fehlersuche bei einem fehlenden Bild wiederholt Include-Einträge hinzuzufügen. Kläre zuerst, ob die Datei eingeschlossen ist, und ändere dann ihre Metadaten.

Referenziere das PNG und lege den Anzeigebereich fest

Platziere diese Deklaration innerhalb einer vorhandenen MAUI-Seite oder eines Layouts:

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

Die Endung .png ist beabsichtigt. Breite und Höhe fordern einen quadratischen Anzeigebereich an; AspectFit hält das gesamte Bild darin sichtbar. Wenn deine Illustration rechteckig ist, verwende einen passenden Anzeigebereich, statt sie zu strecken, damit sie ein Quadrat füllt. Microsofts Referenz zur Bildskalierung unterscheidet Einpassen, Beschneiden und Strecken.

Der Kompasscode ist ein eigenes Einrichtungsbeispiel, kein aufgezeichneter Geräte-Rendering-Test. Baue ihn in deinem Zielprojekt und prüfe die resultierende Ansicht. Ein korrekter Dateiname allein belegt nicht, dass deine konkrete Grafik wie beabsichtigt gerendert wird.

BaseSize und Layoutgröße lösen unterschiedliche Probleme

BaseSize="48,48" liefert die Ausgangsabmessungen, aus denen MAUI Bilder für verschiedene Pixeldichten ableitet. Ohne explizite Ausgangsgröße verwendet MAUI die eigenen Abmessungen des SVG. Microsoft dokumentiert beide Regeln unter Bildgröße ändern.

In diesem Beispiel verwendet die Quellzeichnung einen Koordinatenraum von 96 mal 96, während angeforderte Ausgangsgröße und Ansicht 48 mal 48 sind. Diese Zahlen sind bewusst gewählte Gestaltungswerte, keine gemessenen Ausgabeabmessungen eines Builds. Der Ring sollte beim Skalieren seine Proportionen behalten.

Wenn du dasselbe Emblem später in einer viel größeren Ansicht verwendest, prüfe die Buildgröße erneut und untersuche auch diese Verwendung. Das Ändern von WidthRequest bearbeitet weder Quellgrafik noch Buildmetadaten. Umgekehrt entfernt das Ändern von BaseSize keine leeren Ränder innerhalb des SVG. Passe die Zeichnungsgrenzen in der Quelle enger an, wenn das Emblem selbst innerhalb einer ansonsten korrekt großen Ansicht zu klein aussieht.

Verwende Resize="false" nicht als allgemeinen Schärfefix. Es deaktiviert in dieser Verarbeitung die Größenanpassung von Vektorbildern. Wähle es nur, wenn du dieses Verhalten möchtest, entsprechend der dokumentierten Resize-Option.

Prüfe ein fehlendes oder unerwartetes Bild der Reihe nach

1. Bestätige Dateinamen und Projektelement. Verwende einen kleingeschriebenen Namen wie compass.svg und suche nach einem anderen Bild mit demselben Namen. Microsofts Benennungsregeln verlangen eindeutige Bildnamen und Android-kompatible Zeichen.
2. Prüfe die Quelle der Ansicht. Verwende für den Ablauf mit mitgeliefertem SVG compass.png in XAML oder C#.
3. Vergleiche den vorgesehenen Anzeigebereich mit der Ausgangsgröße. Eine Ansichtsgrößenänderung und eine Buildgrößenänderung gehören an unterschiedliche Stellen.
4. Prüfe die Grafik selbst. Ist die Ringmitte noch offen? Ist die korallfarbene Nadel deutlich? Ist das Emblem zentriert, oder schiebt unsichtbarer Quellleerraum es zur Seite?

Prüfe auch Bildmetadaten, die die Farbgebung ändern. Der Projektbilder-Leitfaden dokumentiert TintColor und Color für Einfärbung und Hintergrundfarbe. Lass sie bei diesem zweifarbigen Beispiel ungesetzt, sofern du sein Erscheinungsbild nicht ändern möchtest. Prüfe das Bild vor dem tatsächlichen Seitenhintergrund, auf dem eine verlorene transparente Öffnung leichter auffällt.

Wenn du SVG-Verhalten zur Laufzeit brauchst

Heruntergeladene SVG-Inhalte, interaktive Pfade oder Laufzeitbearbeitungen brauchen eine separate Implementierungsentscheidung. Die obigen Anweisungen zu mitgelieferten Bildern belegen keine Unterstützung für diese Aufgaben.

Zum Beispiel dokumentiert das Vapolia-SVG-Beispielprojekt eigene Steuerelemente SvgImage und SvgImageSource sowie die Einrichtung eingebetteter Ressourcen. Hier gelten andere Anforderungen an das Laden. Bewerte vor der Einführung die unterstützten Renderer-Funktionen und Zielplattformen mit deiner tatsächlichen Datei; das Austauschen der Dateiendung in einer normalen Image-Deklaration installiert keinen Renderer.

Dieselbe Grafik braucht auch in Flutters SVG-Bildablauf, SwiftUIs Asset-Katalog und einem Android-VectorDrawable-Import unterschiedliche Einrichtung. Verwende die Quell-Masterdatei wieder und folge dann den Regeln jedes Ziels.

Bereite eine Vektor-Masterdatei vor, wenn nur ein PNG bleibt

Wenn Kompass oder Logo nur als PNG vorliegt, kann PerfectVector bearbeitbare SVG-Grafik erstellen, bevor du sie dem MAUI-Projekt hinzufügst. Konvertiere das PNG in SVG und prüfe dann Ringöffnung, kleine getrennte Teile und Abstände in einem Editor. Behalte eine saubere Masterdatei für spätere Größen- oder Farbänderungen.

Vektorisierung repariert keine MauiImage-Deklaration und verwandelt die Verarbeitung mitgelieferter Bilder nicht in einen Laufzeit-SVG-Parser. Wenn die Quelle bereits ein bearbeitbares SVG ist, arbeite direkt an Projektkonfiguration oder Zeichnung. Fotos und strukturreiche Grafik können als Rasterbilder nützlicher sein; sie nur deshalb nachzuzeichnen, weil die App SVG-Quellen akzeptiert, fügt eine separate Grafikentscheidung hinzu.

FAQ

Warum referenziere ich ein PNG, obwohl ich ein SVG hinzugefügt habe? .NET MAUI konvertiert mitgelieferte SVG-Bildquellen beim Build in PNG. Behalte das SVG im Projekt und referenziere aus XAML oder C# den PNG-Dateinamen.

Legt BaseSize die Größe des Image-Steuerelements fest? BaseSize legt die Ausgangsabmessungen fest, aus denen von der Pixeldichte abhängige Buildbilder abgeleitet werden. Layout und Größenanforderungen der Ansicht steuern ihren Anzeigebereich.

Sollte ich zum Ändern von BaseSize ein weiteres MauiImage Include hinzufügen? Prüfe, ob die Datei bereits eingeschlossen ist, auch über einen Platzhalter. Verwende Update zur Änderung der Metadaten eines vorhandenen Elements; verwende Include nur, wenn das Element hinzugefügt werden muss.

Lädt dies ein SVG, das nach dem App-Build heruntergeladen wurde? Der Ablauf für mitgelieferte Bilder deckt Herunterladen und Parsen von SVG zur Laufzeit nicht ab. Wähle und teste für diese Anforderung einen Laufzeit-Rendering-Ansatz.

Quellen

1. Microsoft — Bilder zu einem .NET-MAUI-App-Projekt hinzufügen — SVG-zu-PNG-Verarbeitung, Bildelemente, Dateinamen, Ausgangsgröße und Buildmetadaten.
2. Microsoft — Image — Lokale Bildreferenzen, Auswahl der Zielpixeldichte, Ansichtsgrößen und Skalierungsverhalten.
3. Microsoft — Item-Element (MSBuild) — Unterschied zwischen dem Hinzufügen eines Elements mit Include und dem Ändern vorhandener Metadaten mit Update.
4. Vapolia — SVG-Beispiele — Separates Laufzeit-SVG-Steuerelement und Ressourcenladeablauf.

Arbeitest du mit einem App-Emblem, das nur als Rasterbild vorliegt? Verwandle dein PNG in ein bearbeitbares SVG, prüfe Öffnungen und Abstände, füge diese Masterdatei dann MAUI hinzu und prüfe das erzeugte Bild in deiner Ziel-App.