SVG w .NET MAUI: zachowaj SVG, odwołuj się do PNG

Aby używać SVG w .NET MAUI w ramach obsługi obrazów dołączanych do aplikacji, zachowaj SVG w projekcie i odwołuj się do nazwy wygenerowanego pliku PNG z XAML lub C#. MAUI przetwarza źródłową grafikę wektorową podczas kompilacji. Dlatego odwołanie kontrolki Image do compass.png może być poprawne, nawet gdy dodany przez Ciebie plik to compass.svg. Przewodnik Microsoft dotyczący obrazów w projekcie opisuje tę konwersję.

To wyjaśnia nazwę pliku, ale pozostawia pytanie projektowe: jaki rozmiar obrazu ma wygenerować MAUI i co należy później sprawdzić? Prześledź niewielki symbol kompasu od pliku źródłowego, przez metadane projektu, po deklarację sposobu wyświetlania.

Prześledź drogę pliku źródłowego przez proces kompilacji

Edytowalny SVG i obraz umieszczony w pakiecie aplikacji pełnią różne funkcje. Zachowaj źródło, aby później móc dostosować jego kształty, puste przestrzenie lub kolory. W widoku, który wyświetla obraz, używaj wygenerowanej nazwy.

Dokumentacja kontrolki Image opisuje dołączanie do pakietu aplikacji obrazów dla docelowych gęstości pikseli oraz wybór odpowiedniej rozdzielczości przez system operacyjny. Zachowanie wzorcowego pliku SVG nie oznacza, że ten konkretny proces dostarcza do widoku dokument SVG przetwarzany na bieżąco.

Dodaj niewielki SVG z jasno określonymi granicami

Zapisz ten autorski przykład jako 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>

Pierścień pozostawia przezroczysty środek, a koralowa igła jest osobnym kształtem. Te szczegóły dają Ci konkretne punkty do sprawdzenia po imporcie. Zadeklarowane wymiary i kwadratowy viewBox jasno określają też zamierzone kadrowanie. Zobacz przewodnik po plikach SVG, aby poznać różnicę między geometrią wektorową a obrazem rastrowym osadzonym wewnątrz dokumentu SVG.

W projekcie sprawdź, czy plik ma ustawioną akcję kompilacji MauiImage. Microsoft wskazuje folder Resources/Images jako standardową lokalizację. Przed dodaniem XML sprawdź istniejące elementy projektu: Twój projekt może już uwzględniać ten folder za pomocą symbolu wieloznacznego. Instrukcje konfiguracji obrazów w projekcie wyjaśniają lokalizację i akcję kompilacji.

Zaktualizuj istniejący element jeden raz

Jeśli istniejący wpis MauiImage z symbolem wieloznacznym obejmuje już plik kompasu, umieść tę aktualizację metadanych po tym wpisie:

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

Update zmienia metadane elementu, który już istnieje. Nie dodaje brakującego pliku do listy elementów. Jeśli w Twoim projekcie nie ma pasującego wpisu uwzględniającego plik, dodaj go jeden raz z akcją kompilacji MauiImage lub za pomocą jawnego Include. Dokumentacja Microsoft Item element (MSBuild) rozróżnia te operacje.

Pozwala to uniknąć kuszącej próby naprawy: wielokrotnego dodawania wpisów Include podczas szukania przyczyny brakującego obrazu. Najpierw ustal, czy plik jest uwzględniony, a następnie zmień jego metadane.

Odwołaj się do PNG i ustaw obszar wyświetlania

Umieść tę deklarację wewnątrz istniejącej strony lub układu MAUI:

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

Rozszerzenie .png jest celowe. Żądana szerokość i wysokość określają kwadratowy obszar wyświetlania; AspectFit sprawia, że cały obraz pozostaje w nim widoczny. Jeśli Twoja ilustracja jest prostokątna, użyj dopasowanego do niej obszaru wyświetlania zamiast rozciągać ją tak, by wypełniła kwadrat. Dokumentacja Microsoft dotycząca skalowania obrazów rozróżnia dopasowanie, przycinanie i rozciąganie.

Kod kompasu to autorski przykład konfiguracji, a nie zapis testu renderowania na urządzeniu. Skompiluj go we własnym projekcie docelowym i sprawdź wynikowy widok. Sama poprawna nazwa pliku nie potwierdza, że Twoja konkretna grafika renderuje się zgodnie z zamierzeniem.

BaseSize i rozmiar w układzie rozwiązują różne problemy

BaseSize="48,48" określa wymiary bazowe, na podstawie których MAUI tworzy obrazy dla poszczególnych gęstości pikseli. Bez jawnie określonego rozmiaru bazowego MAUI używa wymiarów samego SVG. Microsoft opisuje obie reguły w sekcji Resize an image.

W tym przykładzie rysunek źródłowy używa przestrzeni współrzędnych 96 na 96, a żądany rozmiar bazowy i widok mają 48 na 48. Te liczby są świadomymi decyzjami podjętymi przy tworzeniu grafiki, a nie wymiarami wynikowymi zmierzonymi po kompilacji. Pierścień powinien zachować proporcje podczas skalowania.

Jeśli później użyjesz tego samego symbolu w znacznie większym widoku, ponownie rozważ rozmiar używany podczas kompilacji i sprawdź również to zastosowanie. Zmiana WidthRequest nie modyfikuje grafiki źródłowej ani jej metadanych kompilacji. Z kolei zmiana BaseSize nie usuwa pustych marginesów wewnątrz SVG. Zawęź granice rysunku w źródle, jeśli sam symbol wygląda na zbyt mały w widoku o prawidłowym rozmiarze.

Unikaj używania Resize="false" jako uniwersalnego sposobu poprawy ostrości. Wyłącza ono zmianę rozmiaru obrazów wektorowych w tym procesie. Wybierz je tylko wtedy, gdy właśnie takiego zachowania oczekujesz, zgodnie z udokumentowaną opcją zmiany rozmiaru.

Sprawdzaj brakujący lub nieoczekiwany obraz w tej kolejności

1. Sprawdź nazwę pliku i element projektu. Użyj nazwy zapisanej małymi literami, takiej jak compass.svg, i sprawdź, czy nie ma innego obrazu o tej samej nazwie. Reguły nazewnictwa Microsoft wymagają unikalnych nazw obrazów i znaków zgodnych z wymaganiami Androida.
2. Sprawdź źródło w widoku. W procesie obsługi SVG dołączanego do aplikacji używaj compass.png w XAML lub C#.
3. Porównaj zamierzony obszar wyświetlania z rozmiarem bazowym. Rozmiar widoku i rozmiar używany podczas kompilacji zmienia się w różnych miejscach.
4. Sprawdź samą grafikę. Czy środek pierścienia nadal jest otwarty? Czy koralowa igła jest wyraźnie widoczna jako osobny kształt? Czy symbol jest wyśrodkowany, czy niewidoczna pusta przestrzeń w źródle przesuwa go na bok?

Sprawdź też wszelkie metadane obrazu, które zmieniają jego kolorystykę. Przewodnik dotyczący obrazów w projekcie opisuje TintColor i Color, służące do ustawiania zabarwienia i koloru tła. W tym dwukolorowym przykładzie pozostaw je nieustawione, chyba że zamierzasz zmienić jego wygląd. Sprawdź obraz na rzeczywistym tle strony, na którym łatwiej zauważyć utratę przezroczystego otworu.

Gdy potrzebujesz obsługi SVG w czasie działania aplikacji

Pobierana zawartość SVG, interaktywne ścieżki lub edycja w czasie działania aplikacji wymagają osobnej decyzji dotyczącej implementacji. Powyższe instrukcje obsługi obrazów dołączanych do aplikacji nie potwierdzają obsługi tych zastosowań.

Na przykład projekt z przykładami SVG firmy Vapolia dokumentuje własne kontrolki SvgImage i SvgImageSource oraz konfigurację zasobów osadzonych. To inny sposób ładowania, z innymi wymaganiami. Przed jego wprowadzeniem oceń obsługiwane funkcje renderera i platformy docelowe na podstawie swojego rzeczywistego pliku; zmiana rozszerzenia nazwy pliku w zwykłej deklaracji Image nie instaluje renderera.

Ta sama grafika wymaga też innej konfiguracji w procesie obsługi obrazów SVG we Flutterze, katalogu zasobów SwiftUI oraz przy imporcie do Android VectorDrawable. Wykorzystaj ponownie źródłowy plik wzorcowy, a następnie postępuj zgodnie z regułami każdego środowiska docelowego.

Przygotuj wektorowy plik wzorcowy, gdy pozostał tylko PNG

Jeśli kompas lub logo istnieje wyłącznie jako PNG, PerfectVector może pomóc utworzyć edytowalną grafikę SVG przed dodaniem jej do projektu MAUI. Przekonwertuj PNG na SVG, a następnie sprawdź w edytorze otwór w pierścieniu, drobne oddzielone elementy i odstępy. Zachowaj uporządkowany plik wzorcowy na potrzeby późniejszych zmian rozmiaru lub koloru.

Wektoryzacja nie naprawia deklaracji MauiImage ani nie zmienia procesu obsługi obrazów dołączanych do aplikacji w parser SVG działający w czasie wykonywania. Jeśli źródło jest już edytowalnym SVG, pracuj bezpośrednio nad konfiguracją projektu lub rysunkiem. Zdjęcia i grafiki z teksturami mogą być bardziej przydatne jako obrazy rastrowe; ich wektoryzacja wyłącznie dlatego, że aplikacja przyjmuje źródła SVG, wymaga osobnej decyzji dotyczącej samej grafiki.

FAQ

Dlaczego odwołuję się do PNG, skoro dodany plik to SVG? .NET MAUI podczas kompilacji konwertuje źródłowe obrazy SVG dołączane do aplikacji na PNG. Zachowaj SVG w projekcie i odwołuj się do nazwy pliku PNG z XAML lub C#.

Czy BaseSize ustawia rozmiar kontrolki Image? BaseSize ustawia wymiary bazowe używane do tworzenia podczas kompilacji obrazów dla poszczególnych gęstości pikseli. Układ widoku i żądane rozmiary kontrolują jego obszar wyświetlania.

Czy mam dodać kolejny wpis MauiImage Include, aby zmienić BaseSize? Sprawdź, czy plik jest już uwzględniony, także za pomocą symbolu wieloznacznego. Użyj Update, aby zmienić metadane istniejącego elementu; użyj Include tylko wtedy, gdy trzeba dodać element.

Czy w ten sposób załaduję SVG pobrany po skompilowaniu aplikacji? Proces obsługi obrazów dołączanych do aplikacji nie obejmuje pobierania i parsowania SVG w czasie działania aplikacji. Aby spełnić to wymaganie, wybierz i przetestuj sposób renderowania w czasie działania aplikacji.

Źródła

1. Microsoft — Add images to a .NET MAUI app project — Przetwarzanie SVG na PNG, elementy obrazów, nazwy plików, rozmiar bazowy i metadane kompilacji.
2. Microsoft — Image — Odwołania do obrazów lokalnych, wybór obrazu dla docelowej gęstości pikseli, ustawianie rozmiaru widoku i sposób skalowania.
3. Microsoft — Item element (MSBuild) — Różnica między dodaniem elementu za pomocą Include a zmianą istniejących metadanych za pomocą Update.
4. Vapolia — SVG samples — Osobna kontrolka SVG działająca w czasie wykonywania aplikacji i proces ładowania zasobów.

Pracujesz nad symbolem aplikacji dostępnym wyłącznie jako obraz rastrowy? Zamień swój PNG w edytowalny SVG, sprawdź jego otwory i odstępy, a następnie dodaj ten plik wzorcowy do MAUI i sprawdź wygenerowany obraz w docelowej aplikacji.