PreviewProvider – co to je, protokol SwiftUI a konfigurace v Xcode

Co je PreviewProvider?

PreviewProvider – protokol SwiftUI, který definuje kontrakt pro vytváření obsahu náhledu v Xcode Canvas. Protokol obsahuje jednu povinnou vlastnost: previews typu some View. Jakákoli hodnota vrácená previews se zobrazí v Canvas jako interaktivní náhled. PreviewProvider nevyžaduje dědičnost – stačí statická implementace v extension.

Architektonicky PreviewProvider není součástí běhového prostředí SwiftUI – je to výhradně vývojářský nástroj. Protokol je označen atributem @available(iOS 13.0, *) a není kompilován v release sestavení, protože Xcode používá podmíněný překlad k vyloučení kódu náhledu z produkce. To znamená, že PreviewProvider neovlivňuje velikost binárního souboru a výkon aplikace.

Protokol previews

Vlastnost previews – jediný požadavek PreviewProvider. Musí vrátit libovolné View: od jednoduchého Textu po složitou hierarchii s Group a ForEach. Xcode vykreslí vrácené View v Canvas s použitím systémových nastavení (téma, velikost, písmo).

import SwiftUI

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

// PreviewProvider – statická implementace
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Konvence pojmenování: Apple doporučuje pojmenovat strukturu náhledu jako {ViewName}_Previews. Není to povinný požadavek kompilátoru, ale zlepšuje čitelnost a navigaci v projektu. Xcode automaticky dosadí tuto šablonu při vytváření nového SwiftUI souboru.

Jak funguje PreviewProvider: protokol a metoda previews

Mechanismus fungování PreviewProvider je založen na statickém odesílání: Xcode kompiluje extension s PreviewProvider pouze pro konfiguraci Debug a volá previews během procesu vytváření Canvas. Při každé změně kódu Xcode rekompiluje pouze změněné PreviewProvider, což zajišťuje téměř okamžitou aktualizaci náhledu.

SwiftUI nezaručuje přesnou shodu náhledu s konečným UI na simulátoru nebo zařízení – Canvas používá zjednodušené vykreslování. Animace se zpožděním se mohou zobrazovat nesprávně a některé UIKit komponenty (MapKit, WebView) se v Canvas nevykreslují bez dodatečné konfigurace.

Více náhledů pomocí Group

Group umožňuje současné zobrazení více stavů jednoho View, což urychluje iteraci při navrhování různých konfigurací. Každý náhled uvnitř Group je vykreslen nezávisle.

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 přidá popisek ke každému náhledu v Canvas, což je zvláště užitečné při porovnávání více stavů. Maximální počet náhledů v Group není omezen, ale více než 6–8 zpomaluje Canvas.

Konfigurace náhledu v Xcode

Xcode poskytuje několik modifikátorů pro konfiguraci zobrazení náhledu. Hlavní: previewDevice – emuluje konkrétní zařízení (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout – nastavuje velikost (device, fixed, sizeThatFits). Kombinace těchto modifikátorů poskytuje plnou kontrolu nad prostředím náhledu.

previewDevice přijímá řetězec s názvem zařízení, například „iPhone 16 Pro" nebo „iPad Pro 13-inch (M4)". Seznam dostupných zařízení závisí na nainstalovaných simulátorech v Xcode. Pokud zařízení není nalezeno, Canvas zobrazí náhled na výchozím zařízení bez chyby.

Náhledy pro různá zařízení

Běžná praxe – zobrazení jednoho View na několika zařízeních současně pro kontrolu responzivity. K tomu se používá ForEach s polem názvů zařízení.

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

Příklady PreviewProvider

Praktické příklady ukazují různé scénáře použití PreviewProvider: od jednoduchého náhledu po složité konfigurace s živými daty a kompatibilitou UIKit.

Náhled s mock daty

Mock data – standardní vzor pro náhled, když View přijímá model. Místo skutečného API se dosadí testovací data, což umožňuje vizuální kontrolu stavu UI bez spouštění aplikace.

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")
    }
}

UIKit náhled přes UIViewRepresentable

Kompatibilita s UIKit – PreviewProvider funguje také s UIKit komponentami zabalenými do UIViewRepresentable. To umožňuje náhled existujících UIKit pohledů v SwiftUI Canvas bez migrace celého projektu.

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

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

PreviewProvider a SwiftUI Canvas

Canvas – je vizuální editor Xcode, který vykresluje výsledek PreviewProvider v reálném čase. Bez implementace PreviewProvider zůstává Canvas prázdný. Canvas a PreviewProvider pracují v páru: PreviewProvider určuje, co zobrazit, Canvas – kde a jak.

Je důležité pochopit: Canvas – je prostředí pro spouštění náhledu, nikoli alternativa k PreviewProvider. I když vývojář neotevře Canvas, PreviewProvider lze použít pro rychlou kontrolu kódu prostřednictvím náhledu, který se zobrazí při najetí myší na ikonu Canvas. Podle WWDC 2024 Apple doporučuje psát PreviewProvider pro každé View jako vývojový standard, podobně jako psaní unit testů.

Doporučení: pište PreviewProvider pro každé veřejné View v projektu. To urychluje zaučení nových vývojářů, zjednodušuje code review a umožňuje rychlou kontrolu vizuálních změn bez sestavení celého projektu.

Typické problémy s PreviewProvider

Problém 1: Náhled se neaktualizuje. Pokud Canvas neodráží změny kódu, příčinou je obvykle mezipaměť DerivedData. Vyčistěte DerivedData přes Product → Clean Build Folder (⇧⌘K) nebo ručním smazáním složky ~/Library/Developer/Xcode/DerivedData. Po vyčištění Canvas znovu sestaví náhled od začátku.

Problém 2: PreviewProvider nevidí @StateObject. PreviewProvider vytváří statickou instanci View, proto závislosti vyžadující injekci (ViewModel, služby) musí být předány přes inicializátor nebo @StateObject s výchozí hodnotou. V náhledu používejte mock objekty místo skutečných služeb.

Problém 3: Animace nefungují v Canvas. Canvas nepodporuje všechny SwiftUI animace – zejména ty závislé na čase (withAnimation se zpožděním, .spring). Pro kontrolu animací spusťte aplikaci na simulátoru. Canvas je vhodný pro statickou kontrolu rozvržení.

Oprava PreviewProvider se závislostmi

Injekce závislostí – nejlepší způsob, jak zajistit fungování PreviewProvider se složitými ViewModel. Vytvořte samostatnou instanci ViewModel s testovacími daty a předejte ji do inicializátoru 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)
    }
}

Mock rozšíření: vytvořte extension pro ViewModel, který poskytuje statické .mock instance. To udržuje testovací data poblíž ViewModel a činí PreviewProvider čitelným.