Flutter-SVG-Bilder: Assets bündeln, skalieren und prüfen

Um ein SVG-Asset in Flutter anzuzeigen, füge flutter_svg hinzu, deklariere die Datei in pubspec.yaml und lade denselben Pfad mit SvgPicture.asset. Gib dem Widget Abmessungen oder passende Layoutbeschränkungen und prüfe dann die Grafik in deiner App. Der Asset-Konstruktor des Pakets dokumentiert diesen Ladeweg.

Halte zwei Fragen getrennt: Hat die App die beabsichtigte Datei geladen, und hat der Renderer die beabsichtigte Grafik wiedergegeben? Ein erneuter Zeichnungsexport repariert keinen falsch geschriebenen Asset-Schlüssel. Das Korrigieren des Schlüssels vereinfacht keinen nicht unterstützten Effekt.

Dieser Leitfaden verwendet eine eigene Illustration mit Hügeln und Sonne, um diese Prüfungen übersichtlich zu halten. Der Code folgt der dokumentierten API; er ist kein Bericht über einen kompilierten App-Test.

Beginne mit einer kleinen prüfbaren Quelle

Erstelle in deinem Flutter-Projekt assets/illustrations/hills.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>

Die Quelle hat zwei überlappende dreieckige Hügel und eine abgetrennte bernsteinfarbene Sonne. Sie verwendet explizite Füllungen, enthält weder Text noch verlinkte Bilder und lässt eine sichtbare Lücke zwischen Sonne und Hügeln. Diese Details liefern dir eine kurze Abnahmeliste für die App-Prüfung.

Behalte eine Kopie dieser einfachen Datei, wenn du später deine eigene Grafik einführst. Wenn die kleine Quelle funktioniert, der Ersatz aber nicht, vergleiche ihre Struktur, bevor du die gesamte Ladeeinrichtung änderst.

Ein Flutter-SVG-Asset ist außerdem ein anderer Ausgabeweg als Android-VectorDrawable-XML. Wenn dein Ziel ein natives Android-Drawable ist, verwende den Leitfaden zur Android-VectorDrawable-Vorbereitung, statt beide Dateiformate als austauschbar zu behandeln.

Füge das Paket hinzu und deklariere die genaue Datei

Verwende aus der Flutter-Projektwurzel den offiziellen Installationsbefehl:

flutter pub add flutter_svg

Füge dann diesen Asset-Eintrag unter dem vorhandenen Abschnitt flutter: in pubspec.yaml hinzu:

flutter:
  assets:
    - assets/illustrations/hills.svg

Integriere den Eintrag in deine aktuelle Konfiguration, statt einen zweiten Abschnitt flutter: zu erstellen. Behalte die gezeigte Einrückung. Die Asset-Dokumentation von Flutter definiert diese Pfade relativ zu pubspec.yaml und erklärt, wie die aufgelisteten Dateien ins App-Bundle gelangen.

Verwende im Dateinamen, in der Deklaration und im Dart-Aufruf dieselbe Schreibweise, Groß- und Kleinschreibung und Verzeichnisstruktur. Für diese erste Prüfung lässt sich ein expliziter Dateieintrag leichter vergleichen als ein breiter Ordnereintrag. Wenn du später Verzeichnisse deklarierst, dokumentiert Flutter, dass ein Verzeichniseintrag seine direkten Dateien abdeckt; verschachtelte Verzeichnisse brauchen eigene Einträge.

Baue die App nach einer Änderung der Asset-Konfiguration neu und starte sie mit deinem normalen Entwicklungsablauf. Setze nicht voraus, dass eine im Editor sichtbare Datei bereits in der App enthalten ist, die du gerade betrachtest.

Lade die Grafik in einen definierten Rahmen

Füge diese Imports in die Dart-Datei mit deinem Widget ein:

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

Platziere dieses Widget an einer geeigneten Stelle deines Bildschirms:

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'),
)

Der Rahmen folgt den Proportionen der Quelle. Prüfe die abgetrennte Sonne, beide Hügelfarben und die äußeren Ränder, bevor du eine kleinere Größe ausprobierst. Verwende danach die Abmessungen, die deine tatsächliche Komponente benötigt; die Zahlen oben sind ein Beispiel, keine Mindestgröße oder Leistungsempfehlung.

Die Konstruktordokumentation empfiehlt explizite Abmessungen oder enge Layoutbeschränkungen, damit das Laden das Layout nicht unerwartet ändert. Wenn die Grafik innerhalb des Rahmens zu klein aussieht, prüfe neben den Widget-Abmessungen auch Leerraum in ihrer viewBox.

Die Beschriftung beschreibt den Zweck dieses eigenständigen Bildes. Die semanticsLabel-API verbindet sie mit der semantischen Beschriftung des Bildes. Erwäge bei einem dekorativen Bild neben Text, der die Bedeutung bereits vermittelt, stattdessen den Ausschluss aus der Semantik. Die Konstruktoroption excludeFromSemantics hat Vorrang vor seiner Beschriftung. Prüfe die vorgelesene Bedeutung der gesamten Komponente, statt jede Form einzeln zu beschriften.

Unterscheide Ladeplatzhalter und Fehler

Eine Ladeanzeige beweist nicht, dass ein SVG akzeptiert wurde. Das Paket bietet placeholderBuilder für die Abruf- oder Dekodierungsphase, während die aktuelle errorBuilder-API bei fehlgeschlagenem Laden ein Widget liefert.

Das Beispiel oben verwendet einen kurzen Ersatztext. Ändere während der Entwicklung den Dart-Pfad bewusst auf einen nicht vorhandenen Dateinamen und prüfe, ob du den Fehler erkennen kannst. Stelle den korrekten Pfad wieder her, bevor du fortfährst. So testest du deine Fehlerdarstellung, ohne die Zeichnung selbst zu ändern.

Teste anschließend deine echte Quelle. Wenn sie weiterhin fehlschlägt, prüfe die Diagnoseausgabe und vergleiche zuerst den deklarierten Pfad. Ein Netzwerkbeispiel, das zufällig ein anderes SVG anzeigt, belegt weder, dass deine lokale Datei gebündelt ist, noch dass ihre Funktionen unterstützt werden.

Entscheide zwischen Palettenerhalt und Einfärbung

Lass colorFilter ungesetzt, wenn die Hügel blaugrün und dunkelblau mit bernsteinfarbener Sonne bleiben sollen. Füge für eine bewusst einfarbige Darstellung einen Filter wie diesen hinzu:

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

Das Paket dokumentiert dieses Einfärbungsmuster. Flutters BlendMode-Referenz erklärt, dass srcIn die Deckkraft des Ziels nutzt und seine Farbkanäle ignoriert. Eine gleichmäßige Einfärbung entfernt daher die Unterschiede der Quellpalette; sie ist eine Designentscheidung, keine Reparatur zum Farberhalt.

Prüfe bei den Hügeln, ob der verlorene Kontrast zwischen den beiden überlappenden Dreiecken die Illustration schwerer lesbar macht. Behalte die ursprüngliche Palette, wenn diese Bereiche unterscheidbar bleiben müssen. Das Paket dokumentiert auch ColorMapper für gezielte Ersetzungen, doch beginne bei der Diagnose einer Abweichung mit dem einfacheren ungefilterten Fall.

Vereinfache Funktionen erst, nachdem die Datei geladen ist

Die flutter_svg-Dokumentation empfiehlt beim Export aus Illustrator Präsentationsattribute, weil die CSS-Unterstützung unvollständig ist, sowie eingebettete statt extern verlinkter Bilder. Sie bietet außerdem eine compilerbasierte Kompatibilitätsprüfung. Folge dieser Prüfung in deiner eigenen Flutter-/Dart-Umgebung, wenn ein komplexes Asset untersucht werden muss.

Eine Browser-Vorschau ist eine nützliche Referenz für die gewünschte Darstellung; sie beweist nicht, dass jede SVG-Funktion durch das Paket identisch gerendert wird. Behalte die Originalgrafik und vereinfache eine Kopie jeweils um eine Änderung.

Wenn die Quelle Schrift enthält, entscheide, ob sie App-Text oder feste Grafik bleiben soll. Der Leitfaden zu SVG-Schriftänderungen erklärt, warum die Darstellung von Text- und Schriftbehandlung abhängen kann. Zeichne keine Beschriftung nach, nur um ein Asset-Pfadproblem zu lösen.

Vergleiche bei einer UI-Asset-Familie ihre sichtbare Größe und Abstände gemeinsam. Der Leitfaden zur UI-Kit-Icon-Vorbereitung hilft bei dieser Konsistenzprüfung.

Verwende Vektorisierung, wenn die Quelle rekonstruiert werden muss

Behalte ein sauberes vorhandenes SVG. Ein Foto oder strukturreicher Hintergrund wird möglicherweise besser als geeignetes Raster-Asset ausgeliefert; das Ändern der Dateiendung macht daraus keine nützliche Vektorgeometrie.

Wenn eine einfache Illustration nur als grobes PNG erhalten ist, kann PerfectVectors PNG-zu-SVG-Ablauf helfen, eine bearbeitbare SVG-Version vorzubereiten. Schneide auf die Grafik zu, prüfe die Vorschau auf fehlende Formen und unerwünschte Hintergrundbereiche und lade das SVG herunter. Füge diese Datei zum App-Bundle hinzu und wiederhole die Prüfungen für Laden, Palette, Größe und Semantik.

Achte beim Hügelbeispiel auf die abgetrennte Sonne und die Trennung der beiden farbigen Hänge. Bestätige, dass die Datei die beabsichtigte Struktur enthält; der Leitfaden zu eingebetteten Rasterbildern erklärt, warum ein SVG-Container weiterhin Pixel enthalten kann.

Beurteile das Asset in der App, bevor du eine Optimierungsstrategie wählst. Dieser Ablauf verspricht nicht allgemein, dass ein SVG kleiner oder schneller als ein PNG ist.

Wenn du die Grafik in einer .NET-MAUI-App wiederverwendest, folge dem MAUI-Quelle-zu-PNG-Ablauf. Das Projekt behält die SVG-Masterdatei, während die Ansicht ein beim Build vorbereitetes PNG referenziert.

FAQ

Wie füge ich Flutter ein SVG-Bild hinzu? Füge flutter_svg hinzu, deklariere das SVG-Asset in pubspec.yaml und lade den passenden Pfad mit SvgPicture.asset. Lege Abmessungen oder geeignete Beschränkungen fest und prüfe das Ergebnis.

Warum erscheint mein lokales SVG nicht? Prüfe zuerst Asset-Deklaration, genauen Pfad, Ladefehler und Layout. Wenn eine einfache Quelle funktioniert, vergleiche die Struktur und unterstützten Funktionen der fehlschlagenden Grafik.

Warum wurden alle Farben gleich? Ein gleichmäßiger srcIn-Farbfilter ersetzt die sichtbare Palette durch seine Einfärbung. Entferne diesen Filter, wenn die ursprünglichen Farben unterscheidbar bleiben sollen.

Muss ich ein PNG für Flutter in SVG verwandeln? Nein. Verwende ein geeignetes Raster-Asset, wenn es zur Grafik passt. Vektorisierung ist optional, wenn du bearbeitbare Formen aus einer einfachen Rasterquelle rekonstruieren möchtest.

Quellen

1. flutter_svg — Installation — Paketinstallation und Dart-Import.
2. Flutter — Assets und Bilder hinzufügen — Asset-Deklarationen, Pfade und Bündelung.
3. flutter_svg — SvgPicture.asset — Asset-Laden, Abmessungen, Einpassung und Semantikeinstellungen.
4. flutter_svg — errorBuilder — Fehlerdarstellung getrennt von Ladeplatzhaltern.
5. flutter_svg — semanticsLabel — Semantischer Zweck des Bildes.
6. Flutter — BlendMode — Deckkraftbasierte srcIn-Farbbehandlung.
7. flutter_svg — Paketdokumentation — Einfärbung, gezielte Farbzuordnung, Exporthinweise und Kompatibilitätsprüfungen.

Beginne mit einem deklarierten Asset und prüfe Pfad, Palette, Größe und Bedeutung in deiner App. Wenn eine Rasterillustration rekonstruiert werden muss, bereite einen SVG-Kandidaten vor, prüfe seine Formen und führe dieselben Prüfungen durch, bevor du sie deiner Asset-Familie hinzufügst.