Obrazy SVG we Flutterze: pakowanie, rozmiar i sprawdzanie zasobów

Aby wyświetlić zasób SVG we Flutterze, dodaj flutter_svg, zadeklaruj plik w pubspec.yaml i załaduj tę samą ścieżkę za pomocą SvgPicture.asset. Nadaj widżetowi wymiary lub odpowiednie ograniczenia układu, a następnie sprawdź grafikę w aplikacji. Ten sposób ładowania opisuje dokumentacja konstruktora pakietu służącego do ładowania zasobów.

Rozpatruj osobno dwie kwestie: czy aplikacja załadowała właściwy plik i czy renderer odtworzył zamierzoną grafikę? Ponowny eksport rysunku nie naprawi błędnie zapisanego klucza zasobu. Poprawienie klucza nie uprości nieobsługiwanego efektu.

W tym poradniku wykorzystujemy autorską ilustrację wzgórz i słońca, aby ułatwić te kontrole. Kod jest zgodny z udokumentowanym API; nie jest to raport z testu skompilowanej aplikacji.

Zacznij od niewielkiego pliku źródłowego, który możesz sprawdzić

Utwórz assets/illustrations/hills.svg w swoim projekcie Flutter:

<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>

Plik źródłowy zawiera dwa nakładające się trójkątne wzgórza i oddzielone od nich bursztynowe słońce. Używa jawnie określonych wypełnień, nie zawiera tekstu ani obrazów dołączonych przez odnośniki i pozostawia widoczny odstęp między słońcem a wzgórzami. Te szczegóły tworzą krótką listę kryteriów akceptacji podczas sprawdzania aplikacji.

Zachowaj kopię tego prostego pliku, gdy później zaczniesz wprowadzać własną grafikę. Jeśli niewielki plik źródłowy działa, a jego zamiennik nie, porównaj ich strukturę, zanim zmienisz całą konfigurację ładowania.

Zasób SVG we Flutterze trafia do aplikacji także inną drogą niż plik XML Android VectorDrawable. Jeśli Twoim celem jest natywny zasób drawable Androida, skorzystaj z poradnika przygotowania Android VectorDrawable, zamiast traktować te dwa formaty plików jako zamienne.

Dodaj pakiet i zadeklaruj dokładny plik

W katalogu głównym projektu Flutter użyj oficjalnego polecenia instalacji:

flutter pub add flutter_svg

Następnie dodaj ten wpis zasobu w istniejącej sekcji flutter: pliku pubspec.yaml:

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

Włącz wpis do obecnej konfiguracji, zamiast tworzyć drugą sekcję flutter:. Zachowaj pokazane wcięcia. Dokumentacja zasobów Fluttera definiuje te ścieżki względem pubspec.yaml i wyjaśnia, jak wymienione pliki trafiają do pakietu aplikacji.

Używaj tej samej pisowni, wielkości liter i struktury katalogów w nazwie pliku, deklaracji i wywołaniu w Darcie. Podczas tej pierwszej kontroli jawny wpis pliku łatwiej porównać niż ogólny wpis folderu. Jeśli później zadeklarujesz katalogi, dokumentacja Fluttera wskazuje, że wpis katalogu obejmuje pliki znajdujące się bezpośrednio w nim; zagnieżdżone katalogi wymagają osobnych wpisów.

Po zmianie konfiguracji zasobów ponownie zbuduj i uruchom aplikację zgodnie ze swoim zwykłym procesem pracy. Nie zakładaj, że plik widoczny w edytorze jest już dołączony do aplikacji, którą oglądasz.

Załaduj grafikę do obszaru o określonych wymiarach

Dodaj te importy do pliku Dart zawierającego Twój widżet:

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

Umieść ten widżet w odpowiedniej części ekranu:

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

Obszar zachowuje proporcje pliku źródłowego. Sprawdź oddzielone słońce, kolory obu wzgórz i zewnętrzne marginesy, zanim wypróbujesz mniejszy rozmiar. Następnie użyj wymiarów wymaganych przez Twój rzeczywisty komponent; powyższe liczby to przykład, a nie minimalny rozmiar ani zalecenie dotyczące wydajności.

Dokumentacja konstruktora zaleca jawne wymiary lub ścisłe ograniczenia układu, aby ładowanie nie zmieniło niespodziewanie układu. Jeśli grafika wygląda na zbyt małą w swoim obszarze, sprawdź pustą przestrzeń w jej viewBox, a także wymiary widżetu.

Etykieta opisuje przeznaczenie tego samodzielnego obrazu. API semanticsLabel wiąże ją z etykietą semantyczną obrazu. W przypadku dekoracyjnego obrazu obok tekstu, który już przekazuje znaczenie, rozważ wykluczenie obrazu z semantyki. Opcja konstruktora excludeFromSemantics ma pierwszeństwo przed jego etykietą. Oceń znaczenie całego komponentu odczytywane na głos, zamiast osobno etykietować każdy kształt.

Odróżnij element zastępczy podczas ładowania od błędu

Wskaźnik ładowania nie jest dowodem na to, że plik SVG został zaakceptowany. Pakiet udostępnia placeholderBuilder na czas pobierania lub dekodowania, natomiast obecne API errorBuilder dostarcza widżet, gdy ładowanie obrazu się nie powiedzie.

Powyższy przykład używa krótkiego tekstu zastępczego w razie błędu. Podczas pracy nad aplikacją celowo zmień ścieżkę w Darcie na nazwę nieistniejącego pliku i sprawdź, czy potrafisz rozpoznać błąd. Przywróć poprawną ścieżkę, zanim przejdziesz dalej. W ten sposób przetestujesz sposób prezentowania błędu bez zmieniania samego rysunku.

Następnie przetestuj swój rzeczywisty plik źródłowy. Jeśli nadal nie działa, sprawdź komunikaty diagnostyczne i najpierw porównaj zadeklarowaną ścieżkę. Przykład pobierający obraz z sieci, który akurat wyświetla inny plik SVG, nie potwierdza, że Twój lokalny plik jest dołączony do pakietu aplikacji ani że użyte w nim funkcje są obsługiwane.

Zdecyduj, czy zachować paletę, czy zastosować jednolite zabarwienie

Nie ustawiaj colorFilter, jeśli wzgórza mają pozostać turkusowe i granatowe, a słońce bursztynowe. Aby celowo uzyskać jednokolorowy efekt, dodaj filtr, na przykład:

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

Pakiet dokumentuje ten sposób barwienia. Dokumentacja BlendMode Fluttera wyjaśnia, że srcIn używa krycia obrazu docelowego, ignorując jego kanały kolorów. Jednolite zabarwienie usuwa więc różnice w palecie źródłowej; to decyzja projektowa, a nie sposób rozwiązania problemu z zachowaniem oryginalnych kolorów.

W przypadku wzgórz sprawdź, czy utrata kontrastu między dwoma nakładającymi się trójkątami utrudnia odczytanie ilustracji. Zachowaj oryginalną paletę, jeśli te obszary muszą pozostać rozróżnialne. Pakiet dokumentuje również ColorMapper do selektywnych zamian kolorów, ale podczas diagnozowania rozbieżności zacznij od prostszego wariantu bez filtra.

Upraszczaj elementy dopiero po załadowaniu pliku

Dokumentacja flutter_svg zaleca używanie atrybutów prezentacji podczas eksportu z Illustratora, ponieważ obsługa CSS jest niepełna, oraz osadzanie obrazów zamiast dołączania ich przez zewnętrzne odnośniki. Udostępnia również kontrolę zgodności opartą na kompilatorze. Przeprowadź tę kontrolę we własnym środowisku Flutter/Dart, gdy złożony zasób wymaga zbadania.

Podgląd w przeglądarce jest przydatnym punktem odniesienia dla zamierzonego wyglądu; nie dowodzi, że każda funkcja SVG będzie renderowana identycznie przez pakiet. Zachowaj oryginalną grafikę i upraszczaj jej kopię, wprowadzając po jednej zmianie.

Jeśli plik źródłowy zawiera napisy, zdecyduj, czy powinny pozostać tekstem aplikacji, czy stałą grafiką. Poradnik dotyczący zmian fontów w SVG wyjaśnia, dlaczego wygląd może zależeć od obsługi tekstu i fontów. Nie wektoryzuj etykiety tylko po to, by rozwiązać problem ze ścieżką zasobu.

W przypadku rodziny zasobów interfejsu porównaj razem ich wizualny rozmiar i odstępy. Poradnik przygotowania ikon do zestawu UI pomoże sprawdzić tę spójność.

Użyj wektoryzacji, gdy trzeba odtworzyć grafikę źródłową

Zachowaj istniejący, poprawny plik SVG. Fotografię lub teksturowane tło lepiej czasem dostarczyć jako odpowiedni zasób rastrowy; zmiana rozszerzenia nie tworzy użytecznej geometrii wektorowej.

Jeśli prosta ilustracja zachowała się tylko jako niedopracowany plik PNG, proces konwersji PNG na SVG w PerfectVector może pomóc przygotować wersję do edycji i oceny. Przytnij obraz do grafiki, sprawdź w podglądzie brakujące kształty i niepożądane obszary tła, a następnie pobierz SVG. Dodaj ten plik do pakietu aplikacji i powtórz kontrolę ładowania, palety, rozmiaru i semantyki.

W przykładzie ze wzgórzami zwróć uwagę na oddzielone słońce i rozróżnienie między dwoma kolorowymi zboczami. Potwierdź, że plik zawiera zamierzoną strukturę; poradnik dotyczący osadzonego obrazu rastrowego wyjaśnia, dlaczego plik SVG może nadal zawierać piksele.

Oceń zasób w aplikacji, zanim wybierzesz strategię optymalizacji. Ten proces nie daje ogólnej gwarancji, że SVG będzie mniejszy lub szybszy niż PNG.

Jeśli ponownie wykorzystasz grafikę w aplikacji .NET MAUI, zastosuj proces przygotowania PNG z pliku źródłowego w MAUI. Projekt zachowuje główny plik SVG, natomiast widok odwołuje się do pliku PNG przygotowanego podczas budowania.

Najczęściej zadawane pytania

Jak dodać obraz SVG do Fluttera? Dodaj flutter_svg, zadeklaruj zasób SVG w pubspec.yaml i załaduj pasującą ścieżkę za pomocą SvgPicture.asset. Ustaw wymiary lub odpowiednie ograniczenia i sprawdź wynik.

Dlaczego mój lokalny plik SVG się nie pojawia? Najpierw sprawdź deklarację zasobu, dokładną ścieżkę, błąd ładowania i układ. Jeśli prosty plik źródłowy działa, porównaj strukturę niedziałającej grafiki i obsługiwane funkcje.

Dlaczego wszystkie kolory stały się takie same? Jednolity filtr kolorów srcIn zastępuje widoczną paletę swoim zabarwieniem. Usuń ten filtr, jeśli oryginalne kolory powinny pozostać rozróżnialne.

Czy muszę zamienić PNG na SVG dla Fluttera? Nie. Użyj odpowiedniego zasobu rastrowego, jeśli pasuje do grafiki. Wektoryzacja jest opcjonalna, gdy odtwarzasz edytowalne kształty z prostego obrazu rastrowego.

Źródła

1. flutter_svg — Installing — Instalacja pakietu i import w Darcie.
2. Flutter — Adding assets and images — Deklaracje zasobów, ścieżki i dołączanie do pakietu aplikacji.
3. flutter_svg — SvgPicture.asset — Ładowanie zasobów, wymiary, dopasowanie i opcje semantyki.
4. flutter_svg — errorBuilder — Prezentacja błędu odrębna od elementów zastępczych podczas ładowania.
5. flutter_svg — semanticsLabel — Semantyczne przeznaczenie obrazu.
6. Flutter — BlendMode — Barwienie srcIn oparte na kryciu.
7. flutter_svg — Package documentation — Barwienie, selektywne mapowanie kolorów, wskazówki dotyczące eksportu i kontrole zgodności.

Zacznij od jednego zadeklarowanego zasobu i sprawdź jego ścieżkę, paletę, rozmiar oraz znaczenie w swojej aplikacji. Jeśli ilustracja rastrowa wymaga odtworzenia, przygotuj wersję SVG do oceny, sprawdź jej kształty i przeprowadź te same kontrole, zanim dodasz ją do swojej rodziny zasobów.