PreviewProvider – co to jest, protokół SwiftUI i konfiguracja w Xcode

Czym jest PreviewProvider?

PreviewProvider – protokół SwiftUI definiujący kontrakt do tworzenia treści podglądu w Xcode Canvas. Protokół zawiera jedną obowiązkową właściwość: previews typu some View. Każda wartość zwrócona przez previews jest wyświetlana w Canvas jako interaktywny podgląd. PreviewProvider nie wymaga dziedziczenia – wystarczy statyczna implementacja w extension.

Architektonicznie PreviewProvider nie jest częścią środowiska wykonawczego SwiftUI – to wyłącznie narzędzie programistyczne. Protokół jest oznaczony atrybutem @available(iOS 13.0, *) i nie jest kompilowany w wersji release, ponieważ Xcode używa kompilacji warunkowej do wykluczenia kodu podglądu z produkcji. Oznacza to, że PreviewProvider nie wpływa na rozmiar pliku binarnego ani wydajność aplikacji.

Protokół previews

Właściwość previews – jedyny wymóg PreviewProvider. Musi zwracać dowolną View: od prostego Text do złożonej hierarchii z Group i ForEach. Xcode renderuje zwróconą View w Canvas, stosując ustawienia systemowe (motyw, rozmiar, czcionkę).

import SwiftUI

struct GreetingView: View {
    let name: String
    
    var body: some View {
        Text("Witaj, \(name)!")
            .padding()
    }
}

// PreviewProvider – statyczna implementacja
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Konwencja nazewnictwa: Apple zaleca nazywanie struktury podglądu jako {ViewName}_Previews. Nie jest to obowiązkowy wymóg kompilatora, ale poprawia czytelność i nawigację po projekcie. Xcode automatycznie podstawia ten szablon przy tworzeniu nowego pliku SwiftUI.

Jak działa PreviewProvider: protokół i metoda previews

Mechanizm działania PreviewProvider opiera się na statycznym wysyłaniu: Xcode kompiluje extension z PreviewProvider tylko dla konfiguracji Debug i wywołuje previews podczas budowania Canvas. Przy każdej zmianie kodu Xcode rekompiluje tylko zmienione PreviewProvider, co zapewnia niemal natychmiastową aktualizację podglądu.

SwiftUI nie gwarantuje dokładnego dopasowania podglądu do końcowego UI na symulatorze lub urządzeniu – Canvas używa uproszczonego renderowania. Animacje z opóźnieniami mogą być wyświetlane nieprawidłowo, a niektóre komponenty UIKit (MapKit, WebView) nie są renderowane w Canvas bez dodatkowej konfiguracji.

Wiele podglądów przez Group

Group pozwala wyświetlić kilka stanów jednej View jednocześnie, co przyspiesza iterację podczas projektowania różnych konfiguracji. Każdy podgląd wewnątrz Group jest renderowany niezależnie.

struct ButtonView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ButtonView(title: "Primary", style: .primary)
                .previewDisplayName("Primary")
            
            ButtonView(title: "Disabled", style: .primary)
                .disabled(true)
                .previewDisplayName("Disabled")
            
            ButtonView(title: "Secondary", style: .secondary)
                .previewDisplayName("Secondary")
        }
    }
}

previewDisplayName dodaje etykietę do każdego podglądu w Canvas, co jest szczególnie przydatne przy porównywaniu wielu stanów. Maksymalna liczba podglądów w Group nie jest ograniczona, ale więcej niż 6–8 spowalnia Canvas.

Konfiguracja podglądu w Xcode

Xcode udostępnia kilka modyfikatorów do konfiguracji wyświetlania podglądu. Najważniejsze: previewDevice – emuluje konkretne urządzenie (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout – ustawia rozmiar (device, fixed, sizeThatFits). Kombinacja tych modyfikatorów daje pełną kontrolę nad środowiskiem podglądu.

previewDevice przyjmuje ciąg znaków z nazwą urządzenia, na przykład „iPhone 16 Pro" lub „iPad Pro 13-inch (M4)". Lista dostępnych urządzeń zależy od zainstalowanych symulatorów w Xcode. Jeśli urządzenie nie zostanie znalezione, Canvas wyświetla podgląd na domyślnym urządzeniu bez błędu.

Podglądy dla różnych urządzeń

Powszechna praktyka – pokazywanie jednej View na kilku urządzeniach jednocześnie, aby sprawdzić responsywność. W tym celu używa się ForEach z tablicą nazw urządzeń.

struct AdaptiveView_Previews: PreviewProvider {
    static var previews: some View {
        ForEach(["iPhone SE (3rd generation)", "iPhone 16 Pro Max", "iPad Pro 13-inch (M4)"], id: \.self) { device in
            AdaptiveView()
                .previewDevice(.previewDevice(device))
                .previewDisplayName(device)
        }
    }
}

Przykłady PreviewProvider

Praktyczne przykłady pokazują różne scenariusze użycia PreviewProvider: od prostego podglądu do złożonych konfiguracji z danymi live i zgodnością z UIKit.

Podgląd z danymi mock

Dane mock – standardowy wzorzec dla podglądu, gdy View przyjmuje model. Zamiast rzeczywistego API podstawiane są dane testowe, co pozwala wizualnie sprawdzić stan UI bez uruchamiania aplikacji.

struct UserProfileView: View {
    let user: User
    
    var body: some View {
        VStack {
            AsyncImage(url: user.avatarURL)
                .clipShape(Circle())
            Text(user.name)
                .font(.title)
            Text(user.bio)
                .font(.body)
                .foregroundColor(.secondary)
        }
    }
}

struct UserProfileView_Previews: PreviewProvider {
    static var previews: some View {
        UserProfileView(user: .mock)
            .previewDisplayName("Profile")
        
        UserProfileView(user: .mockLongName)
            .previewDisplayName("Long Name")
    }
}

Podgląd UIKit przez UIViewRepresentable

Zgodność z UIKit – PreviewProvider działa również z komponentami UIKit owiniętymi w UIViewRepresentable. Pozwala to na podgląd istniejących widoków UIKit w SwiftUI Canvas bez migracji całego projektu.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // Skonfiguruj mapę
    }
}

struct MapView_Previews: PreviewProvider {
    static var previews: some View {
        MapViewRepresentable()
    }
}

PreviewProvider i SwiftUI Canvas

Canvas – to wizualny edytor Xcode, który renderuje wynik działania PreviewProvider w czasie rzeczywistym. Bez implementacji PreviewProvider Canvas pozostaje pusty. Canvas i PreviewProvider działają w parze: PreviewProvider określa co pokazać, Canvas – gdzie i jak.

Ważne jest, aby zrozumieć: Canvas – to środowisko wykonawcze podglądu, a nie alternatywa dla PreviewProvider. Nawet jeśli programista nie otwiera Canvas, PreviewProvider może być używany do szybkiego sprawdzenia kodu przez podgląd po najechaniu na ikonę Canvas. Według WWDC 2024, Apple zaleca pisanie PreviewProvider dla każdej View jako standardu programowania, podobnie jak pisanie testów jednostkowych.

Zalecenie: pisz PreviewProvider dla każdej publicznej View w projekcie. Przyspiesza to wdrażanie nowych programistów, upraszcza code review i pozwala szybko sprawdzać zmiany wizualne bez budowania całego projektu.

Typowe problemy z PreviewProvider

Problem 1: Podgląd nie jest aktualizowany. Jeśli Canvas nie odzwierciedla zmian w kodzie, przyczyną najczęściej jest pamięć podręczna DerivedData. Wyczyść DerivedData przez Product → Clean Build Folder (⇧⌘K) lub ręcznie usuwając folder ~/Library/Developer/Xcode/DerivedData. Po czyszczeniu Canvas przebudowuje podgląd od nowa.

Problem 2: PreviewProvider nie widzi @StateObject. PreviewProvider tworzy statyczną instancję View, więc zależności wymagające wstrzyknięcia (ViewModel, serwisy) muszą być przekazywane przez inicjalizator lub @StateObject z domyślną wartością. Używaj obiektów mock zamiast rzeczywistych serwisów w podglądzie.

Problem 3: Animacje nie działają w Canvas. Canvas nie obsługuje wszystkich animacji SwiftUI – szczególnie tych zależnych od czasu (withAnimation z opóźnieniem, .spring). Do sprawdzania animacji uruchamiaj aplikację na symulatorze. Canvas nadaje się do statycznego sprawdzania layoutu.

Naprawa PreviewProvider z zależnościami

Wstrzykiwanie zależności – najlepszy sposób na działanie PreviewProvider ze złożonymi ViewModel. Utwórz osobną instancję ViewModel z danymi testowymi i przekaż ją do inicjalizatora View.

struct DashboardView: View {
    @StateObject var viewModel: DashboardViewModel
    
    var body: some View {
        List(viewModel.items) { item in
            Text(item.title)
        }
    }
}

struct DashboardView_Previews: PreviewProvider {
    static var previews: some View {
        DashboardView(viewModel: DashboardViewModel.mock)
    }
}

Rozszerzenia mock: utwórz extension dla ViewModel, który udostępnia statyczne instancje .mock. Pozwala to trzymać dane testowe obok ViewModel i czyni PreviewProvider czytelnym.