PreviewProvider — was es ist, SwiftUI-Protokoll und Einrichtung in Xcode

Was ist PreviewProvider?

PreviewProvider ist ein SwiftUI-Protokoll, das einen Vertrag zur Erstellung von Vorschauinhalten in Xcode Canvas definiert. Das Protokoll enthält eine einzige erforderliche Eigenschaft: previews vom Typ some View. Jeder von previews zurückgegebene Wert wird in Canvas als interaktive Vorschau angezeigt. PreviewProvider erfordert keine Vererbung — eine statische Implementierung in einer Extension ist ausreichend.

Architektonisch ist PreviewProvider kein Teil der SwiftUI-Laufzeit — es ist ausschließlich ein Entwicklungstool. Das Protokoll ist mit dem Attribut @available(iOS 13.0, *) gekennzeichnet und wird nicht in Release-Builds kompiliert, da Xcode bedingte Kompilierung verwendet, um Vorschau-Code aus der Produktion auszuschließen. Das bedeutet, dass PreviewProvider weder die Binärgröße noch die Anwendungsleistung beeinflusst.

Das previews-Protokoll

Die previews-Eigenschaft ist die einzige Anforderung von PreviewProvider. Sie muss jede View zurückgeben: von einem einfachen Text bis zu einer komplexen Hierarchie mit Group und ForEach. Xcode rendert die zurückgegebene View in Canvas unter Anwendung der Systemeinstellungen (Design, Größe, Schriftart).

import SwiftUI

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

// PreviewProvider — static implementation
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Namenskonvention: Apple empfiehlt, die Vorschau-Struktur als {ViewName}_Previews zu benennen. Dies ist keine Compiler-Anforderung, verbessert jedoch die Lesbarkeit und Navigation im Projekt. Xcode fügt diese Vorlage automatisch beim Erstellen einer neuen SwiftUI-Datei ein.

Wie PreviewProvider funktioniert: Protokoll und previews-Methode

Der Arbeitsmechanismus von PreviewProvider basiert auf statischem Dispatch: Xcode kompiliert die PreviewProvider-Erweiterung nur für die Debug-Konfiguration und ruft previews während des Canvas-Erstellungsprozesses auf. Bei jeder Codeänderung kompiliert Xcode nur die geänderten PreviewProvider neu, was nahezu sofortige Vorschauaktualisierungen gewährleistet.

SwiftUI garantiert keine exakte Übereinstimmung zwischen der Vorschau und der endgültigen Benutzeroberfläche auf einem Simulator oder Gerät — Canvas verwendet vereinfachtes Rendering. Animationen mit Verzögerungen können falsch angezeigt werden, und einige UIKit-Komponenten (MapKit, WebView) werden ohne zusätzliche Konfiguration nicht in Canvas gerendert.

Mehrere Vorschauen über Group

Group ermöglicht die gleichzeitige Anzeige mehrerer Zustände einer View und beschleunigt so die Iteration beim Layout verschiedener Konfigurationen. Jede Vorschau innerhalb von Group wird unabhängig gerendert.

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 fügt jeder Vorschau in Canvas eine Beschriftung hinzu, was besonders beim Vergleich mehrerer Zustände nützlich ist. Die maximale Anzahl von Vorschauen in Group ist nicht begrenzt, aber mehr als 6–8 verlangsamen Canvas.

Konfiguration von Vorschauen in Xcode

Xcode bietet mehrere Modifikatoren zur Konfiguration der Vorschauanzeige. Die wichtigsten: previewDevice — emuliert ein bestimmtes Gerät (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — legt die Größe fest (device, fixed, sizeThatFits). Die Kombination dieser Modifikatoren gibt die vollständige Kontrolle über die Vorschauumgebung.

previewDevice akzeptiert eine Zeichenfolge mit dem Gerätenamen, z. B. „iPhone 16 Pro" oder „iPad Pro 13-inch (M4)". Die Liste der verfügbaren Geräte hängt von den in Xcode installierten Simulatoren ab. Wenn das Gerät nicht gefunden wird, zeigt Canvas die Vorschau auf dem Standardgerät ohne Fehler an.

Vorschauen für verschiedene Geräte

Übliche Praxis ist es, eine View auf mehreren Geräten gleichzeitig anzuzeigen, um die Anpassungsfähigkeit zu prüfen. Dazu wird ForEach mit einem Array von Gerätenamen verwendet.

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-Beispiele

Praktische Beispiele zeigen verschiedene Verwendungsszenarien von PreviewProvider: von einfachen Vorschauen bis zu komplexen Konfigurationen mit Live-Daten und UIKit-Kompatibilität.

Vorschau mit Mock-Daten

Mock-Daten sind ein Standardmuster für Vorschauen, wenn eine View ein Modell akzeptiert. Anstelle einer echten API werden Testdaten eingesetzt, was eine visuelle Überprüfung des UI-Zustands ohne Starten der Anwendung ermöglicht.

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-Vorschau über UIViewRepresentable

UIKit-Kompatibilität — PreviewProvider funktioniert auch mit UIKit-Komponenten, die in UIViewRepresentable eingewickelt sind. Dies ermöglicht die Vorschau vorhandener UIKit-Views in SwiftUI Canvas, ohne das gesamte Projekt migrieren zu müssen.

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

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

PreviewProvider und SwiftUI Canvas

Canvas ist der visuelle Editor von Xcode, der die Ausgabe von PreviewProvider in Echtzeit rendert. Ohne eine PreviewProvider-Implementierung bleibt Canvas leer. Canvas und PreviewProvider arbeiten zusammen: PreviewProvider definiert, was angezeigt wird, Canvas definiert, wo und wie.

Wichtig zu verstehen: Canvas ist die Ausführungsumgebung für Vorschauen, kein Ersatz für PreviewProvider. Selbst wenn der Entwickler Canvas nicht öffnet, kann PreviewProvider zur schnellen Code-Überprüfung über die Popup-Vorschau beim Überfahren des Canvas-Symbols verwendet werden. Laut WWDC 2024 empfiehlt Apple, PreviewProvider für jede View als Entwicklungsstandard zu schreiben, ähnlich wie das Schreiben von Unit-Tests.

Empfehlung: Schreiben Sie PreviewProvider für jede öffentliche View im Projekt. Dies beschleunigt das Onboarding neuer Entwickler, vereinfacht Code-Reviews und ermöglicht die schnelle Überprüfung visueller Änderungen ohne das gesamte Projekt zu bauen.

Häufige Probleme mit PreviewProvider

Problem 1: Vorschau wird nicht aktualisiert. Wenn Canvas Codeänderungen nicht widerspiegelt, liegt die Ursache meist im DerivedData-Cache. Leeren Sie DerivedData über Product → Clean Build Folder (⇧⌘K) oder löschen Sie manuell den Ordner ~/Library/Developer/Xcode/DerivedData. Nach der Bereinigung erstellt Canvas die Vorschau neu.

Problem 2: PreviewProvider sieht @StateObject nicht. PreviewProvider erstellt eine statische Instanz der View, daher müssen Abhängigkeiten, die eine Injektion erfordern (ViewModels, Dienste), über den Initialisierer oder @StateObject mit einem Standardwert übergeben werden. Verwenden Sie in Vorschauen Mock-Objekte anstelle echter Dienste.

Problem 3: Animationen funktionieren nicht in Canvas. Canvas unterstützt nicht alle SwiftUI-Animationen — insbesondere solche, die von der Zeit abhängen (withAnimation mit Verzögerung, .spring). Zum Testen von Animationen führen Sie die Anwendung auf einem Simulator aus. Canvas eignet sich für die statische Layout-Überprüfung.

PreviewProvider mit Abhängigkeiten reparieren

Abhängigkeitsinjektion ist der beste Weg, PreviewProvider mit komplexen ViewModels zum Funktionieren zu bringen. Erstellen Sie eine separate ViewModel-Instanz mit Testdaten und übergeben Sie sie an den View-Initialisierer.

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-Erweiterungen: Erstellen Sie eine Extension für das ViewModel, die statische .mock-Instanzen bereitstellt. Dies hält Testdaten nahe am ViewModel und macht PreviewProvider lesbar.