PreviewProvider – mi ez, SwiftUI protokoll és konfiguráció Xcode-ban

Mi az a PreviewProvider?

PreviewProvider – az a SwiftUI protokoll, amely meghatározza az előnézeti tartalom létrehozására vonatkozó szerződést az Xcode Canvas-ban. A protokoll egyetlen kötelező tulajdonságot tartalmaz: previews some View típusú. A previews által visszaadott bármely érték interaktív előnézetként jelenik meg a Canvas-ban. A PreviewProvider nem igényel öröklődést – elég egy statikus implementáció egy extension-ben.

Architektúrális szempontból a PreviewProvider nem része a SwiftUI futási környezetének – kizárólag fejlesztői eszköz. A protokoll @available(iOS 13.0, *) attribútummal van jelölve, és nem fordul a release build-ben, mert az Xcode feltételes fordítást használ az előnézeti kód kizárására a éles kódból. Ez azt jelenti, hogy a PreviewProvider nem befolyásolja a bináris méretét és az alkalmazás teljesítményét.

A previews protokoll

A previews tulajdonság – a PreviewProvider egyetlen követelménye. Bármilyen View-t vissza kell adnia: az egyszerű Text-től a Group és ForEach segítségével létrehozott összetett hierarchiáig. Az Xcode a visszaadott View-t a Canvas-ban jeleníti meg, alkalmazva a rendszerbeállításokat (téma, méret, betűtípus).

import SwiftUI

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

// PreviewProvider – statikus implementáció
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Elnevezési konvenció: Az Apple azt ajánlja, hogy az előnézeti struktúrát {ViewName}_Previews névre kereszteljék. Ez nem kötelező fordítói követelmény, de javítja az olvashatóságot és a projekten belüli navigációt. Az Xcode automatikusan beilleszti ezt a sablont új SwiftUI fájl létrehozásakor.

Hogyan működik a PreviewProvider: protokoll és a previews metódus

Működési mechanizmus A PreviewProvider statikus küldésen alapul: az Xcode csak a Debug konfigurációhoz fordítja le a PreviewProvider-t tartalmazó extension-t, és meghívja a previews-t a Canvas építése során. Minden alkalommal, amikor a kód változik, az Xcode csak a megváltoztatott PreviewProvider-eket fordítja újra, ami szinte azonnali előnézet-frissítést biztosít.

A SwiftUI nem garantálja az előnézet pontos megegyezését a végső UI-lal a szimulátoron vagy eszközön – a Canvas egyszerűsített megjelenítést használ. A késleltetéssel rendelkező animációk helytelenül jelenhetnek meg, és néhány UIKit komponens (MapKit, WebView) nem jelenik meg a Canvas-ban további konfiguráció nélkül.

Több előnézet Group segítségével

A Group lehetővé teszi egy View több állapotának egyidejű megjelenítését, ami felgyorsítja az iterációt különböző konfigurációk tervezésekor. A Group-on belül minden előnézet függetlenül jelenik meg.

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

A previewDisplayName címkét ad minden előnézethez a Canvas-ban, ami különösen hasznos több állapot összehasonlításakor. A Group-ban lévő előnézetek maximális száma nem korlátozott, de több mint 6–8 lelassítja a Canvas-t.

Az előnézet konfigurálása Xcode-ban

Az Xcode számos módosítót kínál az előnézet megjelenítésének konfigurálásához. A főbbek: previewDevice – egy adott eszközt emulál (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout – beállítja a méretet (device, fixed, sizeThatFits). Ezen módosítók kombinációja teljes ellenőrzést biztosít az előnézeti környezet felett.

A previewDevice egy sztringet fogad az eszköz nevével, például „iPhone 16 Pro” vagy „iPad Pro 13-inch (M4)”. Az elérhető eszközök listája az Xcode-ban telepített szimulátoroktól függ. Ha az eszköz nem található, a Canvas hiba nélkül jeleníti meg az előnézetet az alapértelmezett eszközön.

Előnézetek különböző eszközökhöz

Gyakori gyakorlat – egy View egyidejű megjelenítése több eszközön a reszponzivitás ellenőrzéséhez. Ehhez a ForEach használatos eszköznevek tömbjével.

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

PreviewProvider példák

Gyakorlati példák a PreviewProvider különböző használati eseteit mutatják: az egyszerű előnézettől az összetett konfigurációkig élő adatokkal és UIKit kompatibilitással.

Előnézet mock adatokkal

Mock adatok – a szokásos minta az előnézethez, amikor a View egy modellt fogad. A valódi API helyett tesztadatok kerülnek helyettesítésre, ami lehetővé teszi az UI állapotának vizuális ellenőrzését az alkalmazás elindítása nélkül.

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 előnézet UIViewRepresentable segítségével

UIKit kompatibilitás – a PreviewProvider működik UIViewRepresentable-be csomagolt UIKit komponensekkel is. Ez lehetővé teszi a meglévő UIKit nézetek előnézetét SwiftUI Canvas-ban a teljes projekt migrálása nélkül.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // Térkép konfigurálása
    }
}

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

PreviewProvider és SwiftUI Canvas

A Canvas – az Xcode vizuális szerkesztője, amely valós időben jeleníti meg a PreviewProvider eredményét. A PreviewProvider implementálása nélkül a Canvas ürüs marad. A Canvas és a PreviewProvider párban működik: a PreviewProvider meghatározza, hogy mi jelenjen meg, a Canvas – hogy hol és hogyan.

Fontos megérteni: A Canvas – az előnézet végrehajtási környezete, nem a PreviewProvider alternatívája. Még ha a fejlesztő nem is nyitja meg a Canvas-t, a PreviewProvider használható a kód gyors ellenőrzésére a Canvas ikonra húzva megjelenő előnézeten keresztül. A WWDC 2024 szerint az Apple azt ajánlja, hogy a PreviewProvider-t minden View-hoz írják meg, mint fejlesztési szabványt, hasonlóan az unit tesztek írásához.

Ajánlás: írjon PreviewProvider-t minden nyilvános View-hoz a projektben. Ez felgyorsítja az új fejlesztők betanulását, egyszerűsíti a kódellenőrzést, és lehetővé teszi a vizuális változások gyors ellenőrzését a teljes projekt felépítése nélkül.

Gyakori problémák a PreviewProvider-rel

1. probléma: Az előnézet nem frissül. Ha a Canvas nem tükrözi a kódváltozásokat, az ok általában a DerivedData gyorsítótár. Tisztítsa meg a DerivedData-t a Product → Clean Build Folder (⇧⌘K) menün keresztül vagy a ~/Library/Developer/Xcode/DerivedData mappa kézi törlésével. A tisztítás után a Canvas újraépíti az előnézetet.

2. probléma: A PreviewProvider nem látja a @StateObject-t. A PreviewProvider egy statikus példányt hoz létre a View-ról, ezért a befecskendezést igénlő függőségeket (ViewModel, szolgáltatások) az inicializálón vagy @StateObject-en keresztül kell átadni alapértelmezett értékkel. Használjon mock objektumokat a valódi szolgáltatások helyett az előnézetben.

3. probléma: Az animációk nem működnek a Canvas-ban. A Canvas nem támogatja az összes SwiftUI animációt – különösen azokat, amelyek időfüggők (withAnimation késleltetéssel, .spring). Az animációk ellenőrzéséhez futtassa az alkalmazást a szimulátoron. A Canvas statikus layout ellenőrzésre alkalmas.

PreviewProvider javítása függőségekkel

Függőség befecskendezés – a legjobb mód a PreviewProvider működésének biztosítására összetett ViewModel-ekkel. Hozzon létre egy külön ViewModel példányt tesztadatokkal, és adja át a View inicializálójának.

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 kiterjesztések: hozzon létre egy extension-t a ViewModel-hez, amely statikus .mock példányokat biztosít. Ez a tesztadatokat a ViewModel mellett tartja, és olvashatóvá teszi a PreviewProvider-t.