PreviewProvider — qu'est-ce que c'est, protocole SwiftUI et configuration dans Xcode

Qu'est-ce que PreviewProvider ?

PreviewProvider est un protocole SwiftUI qui définit un contrat pour créer du contenu d'aperçu dans Xcode Canvas. Le protocole contient une seule propriété obligatoire : previews de type some View. Toute valeur retournée par previews est affichée dans Canvas comme un aperçu interactif. PreviewProvider ne nécessite pas d'héritage — une implémentation statique dans une extension suffit.

Sur le plan architectural, PreviewProvider ne fait pas partie de l'environnement d'exécution SwiftUI — c'est exclusivement un outil de développement. Le protocole est marqué avec l'attribut @available(iOS 13.0, *) et n'est pas compilé dans la version de publication, car Xcode utilise la compilation conditionnelle pour exclure le code d'aperçu de la production. Cela signifie que PreviewProvider n'affecte pas la taille du binaire ni les performances de l'application.

Le protocole previews

La propriété previews est la seule exigence de PreviewProvider. Elle doit retourner n'importe quelle View : d'un simple Text à une hiérarchie complexe avec Group et ForEach. Xcode rend la View retournée dans Canvas, en appliquant les paramètres système (thème, taille, police).

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

Convention de nommage : Apple recommande de nommer la structure d'aperçu {ViewName}_Previews. Ce n'est pas une exigence du compilateur, mais cela améliore la lisibilité et la navigation dans le projet. Xcode insère automatiquement ce modèle lors de la création d'un nouveau fichier SwiftUI.

Comment fonctionne PreviewProvider : protocole et méthode previews

Le mécanisme de fonctionnement de PreviewProvider est basé sur la répartition statique : Xcode compile l'extension PreviewProvider uniquement pour la configuration Debug et appelle previews pendant le processus de construction de Canvas. Chaque fois que le code change, Xcode ne recompile que les PreviewProvider modifiés, garantissant des mises à jour quasi instantanées de l'aperçu.

SwiftUI ne garantit pas une correspondance exacte entre l'aperçu et l'interface finale sur un simulateur ou un appareil — Canvas utilise un rendu simplifié. Les animations avec des délais peuvent s'afficher incorrectement, et certains composants UIKit (MapKit, WebView) ne se rendent pas dans Canvas sans configuration supplémentaire.

Aperçus multiples via Group

Group permet d'afficher plusieurs états d'une même View simultanément, accélérant l'itération lors de la conception de différentes configurations. Chaque aperçu dans Group est rendu indépendamment.

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 ajoute une étiquette à chaque aperçu dans Canvas, ce qui est particulièrement utile pour comparer plusieurs états. Le nombre maximum d'aperçus dans Group n'est pas limité, mais plus de 6 à 8 ralentissent Canvas.

Configuration des aperçus dans Xcode

Xcode fournit plusieurs modificateurs pour configurer l'affichage des aperçus. Les principaux : previewDevice — émule un appareil spécifique (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — définit la taille (device, fixed, sizeThatFits). La combinaison de ces modificateurs donne un contrôle total sur l'environnement d'aperçu.

previewDevice accepte une chaîne avec le nom de l'appareil, par exemple « iPhone 16 Pro » ou « iPad Pro 13-inch (M4) ». La liste des appareils disponibles dépend des simulateurs installés dans Xcode. Si l'appareil n'est pas trouvé, Canvas affiche l'aperçu sur l'appareil par défaut sans erreur.

Aperçus pour différents appareils

Pratique courante consiste à afficher une même View sur plusieurs appareils simultanément pour vérifier l'adaptabilité. Pour cela, on utilise ForEach avec un tableau de noms d'appareils.

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

Exemples de PreviewProvider

Des exemples pratiques montrent différents scénarios d'utilisation de PreviewProvider : des aperçus simples aux configurations complexes avec des données en direct et la compatibilité UIKit.

Aperçu avec données simulées

Les données simulées sont un modèle standard pour les aperçus lorsqu'une View accepte un modèle. Au lieu d'une API réelle, des données de test sont substituées, permettant une vérification visuelle de l'état de l'interface sans lancer l'application.

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

Aperçu UIKit via UIViewRepresentable

Compatibilité UIKit — PreviewProvider fonctionne également avec les composants UIKit enveloppés dans UIViewRepresentable. Cela permet de prévisualiser des vues UIKit existantes dans SwiftUI Canvas sans migrer l'ensemble du projet.

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 et SwiftUI Canvas

Canvas est l'éditeur visuel de Xcode qui rend la sortie de PreviewProvider en temps réel. Sans implémentation de PreviewProvider, Canvas reste vide. Canvas et PreviewProvider fonctionnent en tandem : PreviewProvider définit quoi afficher, Canvas définit où et comment.

Il est important de comprendre : Canvas est l'environnement d'exécution de l'aperçu, pas une alternative à PreviewProvider. Même si le développeur n'ouvre pas Canvas, PreviewProvider peut être utilisé pour une vérification rapide du code via l'aperçu contextuel au survol de l'icône Canvas. Selon la WWDC 2024, Apple recommande d'écrire PreviewProvider pour chaque View comme standard de développement, à l'instar de l'écriture de tests unitaires.

Recommandation : écrivez PreviewProvider pour chaque View publique dans le projet. Cela accélère l'intégration des nouveaux développeurs, simplifie les révisions de code et permet de vérifier rapidement les modifications visuelles sans compiler l'ensemble du projet.

Problèmes courants avec PreviewProvider

Problème 1 : L'aperçu ne se met pas à jour. Si Canvas ne reflète pas les modifications de code, la cause est généralement le cache DerivedData. Nettoyez DerivedData via Product → Clean Build Folder (⇧⌘K) ou en supprimant manuellement le dossier ~/Library/Developer/Xcode/DerivedData. Après le nettoyage, Canvas reconstruit l'aperçu à partir de zéro.

Problème 2 : PreviewProvider ne voit pas @StateObject. PreviewProvider crée une instance statique de la View, donc les dépendances nécessitant une injection (ViewModels, services) doivent être transmises via l'initialiseur ou @StateObject avec une valeur par défaut. Utilisez des objets simulés au lieu de services réels dans les aperçus.

Problème 3 : Les animations ne fonctionnent pas dans Canvas. Canvas ne prend pas en charge toutes les animations SwiftUI — en particulier celles qui dépendent du temps (withAnimation avec délai, .spring). Pour tester les animations, exécutez l'application sur un simulateur. Canvas est adapté à la vérification statique de la mise en page.

Correction de PreviewProvider avec dépendances

L'injection de dépendances est la meilleure façon de faire fonctionner PreviewProvider avec des ViewModels complexes. Créez une instance séparée de ViewModel avec des données de test et passez-la à l'initialiseur de la 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)
    }
}

Extensions simulées : créez une extension pour le ViewModel qui fournit des instances .mock statiques. Cela maintient les données de test près du ViewModel et rend PreviewProvider lisible.