SVG w SwiftUI: dodawanie zasobów i sterowanie ich kolorem

Aby dołączyć statyczny SVG do aplikacji SwiftUI, umieść grafikę w katalogu zasobów Xcode i wczytaj obraz po nazwie zasobu. Następnie zdecyduj, czy ma zachować oryginalne kolory, czy stać się sylwetką w wybranym kolorze. Apple dodało obsługę zasobów graficznych SVG w Xcode 12; w informacjach o wydaniu wskazano zachowanie grafiki wektorowej dla docelowych wersji systemów iOS 13, iPadOS 13 i macOS 10.15 lub nowszych.

Ten sposób pracy z katalogiem różni się od pobierania pliku SVG podczas działania aplikacji. Różni się też od tworzenia własnego symbolu SF Symbol. Wybierz sposób dostarczania grafiki, zanim ją zmienisz lub dodasz pakiet do renderowania.

Wybierz sposób odpowiedni dla tego konkretnego obrazu

SVG jest plikiem źródłowym. To, jak aplikacja go otrzymuje i wykorzystuje, określa kolejny krok.

Ten przewodnik wykorzystuje pierwszy sposób. Mała filiżanka w dwóch kolorach ułatwia zauważenie dwóch odrębnych błędów: utraty koralowego koloru pary i wypełnienia otworu w uchu. Do zdiagnozowania żadnego z nich nie potrzeba skomplikowanej ilustracji.

Przewodnik przygotowania grafiki do zestawu UI opisuje szerszy proces ujednolicania zestawu. Tutaj chodzi o to, jak jeden zaakceptowany SVG trafia do Image w SwiftUI.

Przygotuj mały plik źródłowy z widocznymi punktami kontrolnymi

Zapisz ten oryginalny przykład jako CupMark.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
  <path d="M12 26H43V45Q43 54 34 54H21Q12 54 12 45Z"
    fill="#147D73"/>
  <path d="M43 30H48Q55 30 55 37Q55 44 48 44H43"
    fill="none" stroke="#147D73" stroke-width="5"/>
  <path d="M24 19Q18 14 25 8M35 19Q29 14 36 8"
    fill="none" stroke="#EB8067" stroke-width="4" stroke-linecap="round"/>
</svg>

Filiżanka jest turkusowa, dwie linie pary są koralowe, a obszar wewnątrz ucha jest pusty. Umieść te trzy cechy na swojej liście kontrolnej. SVG nie zawiera tekstu, zewnętrznego obrazu, filtra ani skryptu, więc stanowi niewielki plik wyjściowy do eksperymentu z katalogiem.

W przypadku własnej grafiki sprawdź plik źródłowy przed importem. Nadmiar pustego obszaru roboczego sprawia, że ikona wygląda na małą, nawet gdy jej widok ma właściwe wymiary. Biały prostokąt tła staje się częścią sylwetki przy renderowaniu szablonowym. Osadzona fotografia pozostaje innym rodzajem treści niż otaczające ją ścieżki; sprawdzenie osadzonego obrazu rastrowego pomaga je rozróżnić.

Przechowuj edytowalny plik główny oddzielnie od kopii przeznaczonej do aplikacji. Jeśli ikona zawiera liternictwo, ustal w pliku głównym, jakiej czcionki użyć lub jak zamienić litery na ścieżki; zobacz proces zmiany czcionek w SVG. Zmiana stylu tekstu w SwiftUI nie zastępuje sprawdzenia liternictwa wewnątrz obrazu.

Dodaj SVG jako zwykły zestaw obrazów

Otwórz katalog zasobów aplikacji, zwykle Assets.xcassets. Dodaj nowy zestaw obrazów i nazwij go CupMark. Przeciągnij SVG do odpowiedniego pola obrazu. Przewodnik Apple po katalogach zasobów opisuje tworzenie zestawów, importowanie zasobów i udostępnianie wariantów przez inspektor Attributes.

W tym przykładzie użyj zestawu obrazów. Nie wybieraj procesu przeznaczonego dla obrazów symboli tylko dlatego, że plik źródłowy ma rozszerzenie .svg.

Po imporcie sprawdź podgląd w katalogu i wszelkie komunikaty diagnostyczne kompilacji. Upewnij się, że katalog należy do targetu aplikacji, który będzie go używać. Jeśli konfiguracja zasobu zawiera warianty dla różnych platform lub trybów wyglądu, upewnij się, że właściwy obraz jest obecny w odpowiedniej konfiguracji, zamiast zakładać, że podgląd reprezentuje każdą konfigurację.

Nazwa CupMark jest nazwą zasobu graficznego używaną poniżej. Nie jest adresem URL do pobierania ani ścieżką do oryginalnego SVG w folderze z projektem graficznym. Inicjalizator Image firmy Apple wyszukuje zasób po nazwie w pakiecie; domyślnie jest to główny pakiet aplikacji. Jeśli obraz należy do innego pakietu zasobów, jawnie wskaż ten pakiet.

W notatkach do przekazania zachowaj rozróżnienie między nazwą pliku a nazwą zasobu. Osoba z zespołu może zmienić nazwę zestawu zasobów bez zmiany nazwy oryginalnego pliku projektu, a kod musi używać nazwy zasobu, który faktycznie wczytuje.

Porównaj renderowanie oryginalne i szablonowe

Po dodaniu zestawu obrazów CupMark użyj tego widoku:

import SwiftUI
 
struct CupComparison: View {
    var body: some View {
        HStack(spacing: 24) {
            Image("CupMark")
                .renderingMode(.original)
                .resizable()
                .scaledToFit()
                .frame(width: 48, height: 48)
                .accessibilityLabel("Cup with rising steam")
 
            Image("CupMark")
                .renderingMode(.template)
                .resizable()
                .scaledToFit()
                .frame(width: 48, height: 48)
                .foregroundStyle(Color.blue)
                .accessibilityLabel("Cup with rising steam")
        }
        .padding()
    }
}

Instancja po lewej jawnie żąda renderowania oryginalnego. Instancja po prawej żąda renderowania szablonowego i ustawia niebieski kolor jako styl pierwszego planu. Dokumentacja Apple dotycząca renderowania szablonowego definiuje tryb szablonowy jako nadawanie koloru pierwszego planu pikselom, które nie są całkowicie przezroczyste. To sposób renderowania sylwetki, a nie polecenie zmiany koloru tylko jednej ścieżki SVG.

W przypadku filiżanki oznacza to, że wersja po prawej powinna mieć niebieską parę i niebieską filiżankę. Rozróżnienie między koralem a turkusem celowo znika. Otwór w uchu powinien pozostać pusty. Jeśli aplikacja wymaga zmiany pary niezależnie od filiżanki, wybierz strukturę dostarczania grafiki, która udostępnia te części oddzielnie, zamiast oczekiwać, że jeden obraz szablonowy pozwoli nadać styl poszczególnym ścieżkom.

Modyfikatory określają też jawnie sposób ustalania rozmiaru. resizable() umożliwia zmianę rozmiaru obrazu, a scaledToFit() zachowuje jego proporcje wewnątrz ramki o rozmiarze 48 punktów. Ramka widoku i obszar roboczy samej grafiki mają odrębne granice: dodatkowe puste miejsce wewnątrz SVG nadal jest częścią pliku źródłowego.

To przykład oparty na dokumentacji, który możesz wypróbować w swoim projekcie, a nie relacja z testu natywnego renderowania. Sprawdź faktycznie skompilowaną aplikację, również przy najmniejszym rozmiarze, w jakim planujesz używać znaku. Czytelny podgląd przy 48 punktach nie dowodzi, że obie linie pary pozostaną przydatne przy 16 punktach.

Zdiagnozuj widoczny wynik, zanim zmienisz plik

Brak obrazu, zmieniony kolor i nieczytelna sylwetka w małym rozmiarze wymagają różnych poprawek.

Zmieniaj jedną warstwę naraz. Jeśli plik źródłowy ma już prawidłowy otwór, ponowna wektoryzacja nie naprawi literówki w nazwie zasobu. Jeśli wyszukiwanie działa, ale tryb szablonowy usuwa rozróżnienie kolorów, dodanie większej liczby kolorów do SVG nie zmieni wybranego trybu renderowania.

W przypadku ikony obok widocznego tekstu sprawdź jej nazwę dostępną dla technologii wspomagających w pełnym kontekście elementu sterującego. Przykład zawiera opis dla każdego obrazu w porównaniu. Dekoracyjne powtórzenie obok elementu sterującego, który ma już nazwę, może wymagać innego podejścia do dostępności; nie przenoś mechanicznie etykiet z widoku porównawczego do każdego miejsca użycia.

Traktuj SVG wczytywane podczas działania aplikacji i SF Symbols jako odrębne decyzje

Obraz wczytywany z katalogu po nazwie nie jest API do pobierania i parsowania dowolnych danych SVG zapisanych w XML. Jeśli plik trafia do aplikacji po jej skompilowaniu, wybierz renderer, który jawnie obsługuje takie dane wejściowe. Na przykład README projektu SVGView opisuje parser i renderer SVG napisane w SwiftUI. Oceń konkretne funkcje SVG używane w Twoich plikach; deklarowany cel pakietu, jakim jest szeroka obsługa formatu, nie dowodzi, że cały Twój zestaw plików wejściowych renderuje się prawidłowo.

Uwzględnij w tej funkcji sposób wczytywania oraz zachowanie w przypadku błędów i nieobsługiwanych plików. Nie dodawaj pakietu wyłącznie dlatego, że starsza odpowiedź twierdzi, iż SwiftUI nie może używać obrazów SVG, jeśli potrzebujesz statycznego obrazu, który można już obsłużyć przez katalog zasobów.

Własne symbole SF Symbols mają inne wymagania dotyczące pliku źródłowego. Apple dokumentuje proces tworzenia i walidacji oparty na szablonie, obejmujący warianty symboli i informacje o wyrównaniu. Zwykły SVG filiżanki nie zyskuje tych właściwości przez umieszczenie go w zestawie obrazów. Użyj tego procesu, gdy aplikacja potrzebuje zachowania właściwego symbolom, i zachowaj wymaganą strukturę szablonu.

Formaty dostarczania grafiki dla poszczególnych platform warto sprawdzać niezależnie. Jeśli ta sama grafika ma również trafić na Androida, skorzystaj z przewodnika przekazywania grafiki w formacie VectorDrawable; zaakceptowanie pliku przez importer jednej platformy nie dowodzi, że zaakceptuje go importer innej.

Gdy Twoja ikona istnieje tylko jako PNG

Jeśli brakuje edytowalnego pliku źródłowego, a PNG przedstawia prostą ikonę, konwerter PNG na SVG PerfectVector może pomóc przygotować wersję grafiki do oceny w tym procesie. Przytnij obraz do ikony, sprawdź w podglądzie, czy nie zniknęły otwory, nie połączyły się szczegóły ani nie pojawiły się niepożądane kształty tła, a następnie porównaj go z oryginałem. Pobierz zaakceptowany SVG i przetestuj go, wykonując te same kontrole zestawu obrazów i trybu renderowania.

Użyj oryginalnej grafiki wektorowej, jeśli jest dostępna. Zachowaj fotografie i obrazy z wieloma efektami w postaci rastrowej, gdy lepiej chroni to ich wygląd. Wektoryzacja przygotowuje geometrię; nie kompiluje katalogu Xcode, nie wybiera pakietu zasobów ani nie tworzy szablonu SF Symbols z wymaganymi wariantami.

Przed przekazaniem zasobu zapisz jego nazwę w katalogu, zamierzone zachowanie w trybie oryginalnym lub szablonowym, minimalny rozmiar wizualny oraz plik źródłowy używany do jego ponownego wygenerowania. Przetestuj w aplikacji jasne i ciemne tło oraz wszystkie obsługiwane warianty wyglądu. Poradniki dotyczące grafiki na blogu opisują przygotowanie pliku źródłowego poprzedzające ten etap dostarczania grafiki.

Najczęściej zadawane pytania

Czy SwiftUI może używać SVG z katalogu zasobów? Tak. Xcode obsługuje zasoby graficzne SVG. Dodaj plik do zwykłego zestawu obrazów i wczytaj nazwany zasób za pomocą Image. Sprawdź docelową wersję systemu i faktyczną kompilację katalogu, zamiast traktować to jako obsługę dowolnych plików SVG wczytywanych podczas działania aplikacji.

Dlaczego mój SVG stał się jednokolorowy? Sprawdź tryb renderowania. Renderowanie szablonowe wykorzystuje widoczny obraz jako sylwetkę w kolorze pierwszego planu. Użyj renderowania oryginalnego, gdy potrzebujesz zachować oryginalne rozróżnienie kolorów grafiki.

Czy Image może wczytać SVG z adresu URL w internecie? Inicjalizator Image przyjmujący nazwę wyszukuje zasób, a nie parsuje SVG z adresu URL. Pliki SVG dostarczane podczas działania aplikacji wymagają odpowiedniego procesu renderowania i wczytywania, który sprawdzisz na swoich rzeczywistych danych wejściowych.

Czy zestaw obrazów SVG jest tym samym co własny SF Symbol? Nie. Własne symbole wykorzystują szablon z wymaganą strukturą, wariantami, informacjami o wyrównaniu i walidacją. Zwykły zestaw obrazów SVG nie zapewnia automatycznie tych właściwości symbolu.

Źródła

1. Apple — Xcode 12 Release Notes — obsługa zasobów graficznych SVG i udokumentowane docelowe wersje systemów zapewniające zachowanie grafiki wektorowej.
2. Apple — Managing assets with asset catalogs — zestawy zasobów, pola importu i warianty.
3. Apple — Image init(_:bundle:) — wyszukiwanie zasobu po nazwie i wskazywanie pakietu.
4. Apple — Image.TemplateRenderingMode — tryby renderowania oryginalnego i szablonowego.
5. Apple — resizable(capInsets:resizingMode:) — jawne określanie sposobu zmiany rozmiaru obrazu.
6. Apple — scaledToFit() — dopasowanie z zachowaniem proporcji.
7. Apple — Creating custom symbol images for your app — szablony własnych symboli, warianty i walidacja.
8. Exyte — SVGView — odrębne rozwiązanie do parsowania i renderowania SVG w SwiftUI.

Sprawdź jedną ikonę w docelowym rozmiarze i trybie kolorów, zanim zaimportujesz cały zestaw. Jeśli pozostał tylko PNG, przygotuj wersję SVG do oceny, sprawdź jej otwory i tło oraz zweryfikuj zaakceptowany plik w skompilowanej aplikacji.