Débogage SwiftUI
Aperçu
Le débogage SwiftUI se divise en trois catégories, chacune avec une approche diagnostique différente :
- La vue ne se met pas à jour – Vous avez changé quelque chose mais la vue ne s'est pas redessinée. Arbre de décision pour identifier s'il s'agit d'une mutation de structure, d'une perte d'identité de liaison, d'une recréation accidentelle de vue ou d'un motif d'observateur manquant.
- Plantages d'aperçu – Votre aperçu ne compile pas ou plante immédiatement. Arbre de décision pour distinguer les dépendances manquantes, les échecs d'initialisation d'état et la corruption du cache Xcode.
- Problèmes de mise en page – Les vues apparaissent dans des positions incorrectes, avec des tailles incorrectes, ou se chevauchent de manière inattendue. Références rapides pour les scénarios courants.
Principe fondamental : Commencez par les symptômes observables, testez systématiquement, éliminez les causes une par une. Ne devinez pas.
Nécessite : Xcode 26+, iOS 17+ (les motifs iOS 14-16 sont toujours valides, voir les notes)
Compétences connexes : axiom-xcode-debugging (diagnostic de corruption de cache), axiom-swift-concurrency (motifs d'observateurs), axiom-swiftui-performance (profilage avec Instruments), axiom-swiftui-layout (motifs de mise en page adaptative)
Exemples de prompts
Voici des questions réelles de développeurs auxquelles cette compétence est conçue pour répondre :
1. « Mon élément de liste ne se met pas à jour lorsque j'appuie sur le bouton favori, même si les données ont changé »
→ La compétence parcourt l'arbre de décision pour identifier la mutation de structure par rapport à la liaison perdue par rapport à l'observateur manquant
2. « L'aperçu plante avec 'Cannot find AppModel in scope' mais il compile correctement »
→ La compétence montre comment fournir les dépendances manquantes avec .environment() ou .environmentObject()
3. « Mon compteur se remet à 0 chaque fois que j'active/désactive un booléen, pourquoi ? »
→ La compétence identifie la recréation accidentelle de vue due aux conditionnels et montre la correction avec .opacity()
4. « J'utilise @Observable mais la vue ne se met toujours pas à jour lorsque je change la propriété »
→ La compétence explique quand utiliser @State par rapport aux propriétés simples avec les objets @Observable
5. « Le champ de texte perd le focus lorsque je commence à taper, très frustrant »
→ La compétence identifie les problèmes d'identité dans ForEach et montre comment utiliser des identifiants stables
Quand utiliser le débogage SwiftUI
Utilisez cette compétence lorsque
- ✅ Une vue ne se met pas à jour comme prévu
- ✅ L'aperçu plante ou ne se charge pas
- ✅ La mise en page semble incorrecte sur des appareils spécifiques
- ✅ Vous êtes tenté de faire un pansement avec @ObservedObject partout
Utilisez axiom-xcode-debugging à la place lorsque
- L'application plante à l'exécution (pas dans l'aperçu)
- La construction échoue complètement
- Vous avez besoin de diagnostics d'environnement
Utilisez axiom-swift-concurrency à la place lorsque
- Vous avez des questions sur async/await ou MainActor
- Vous avez des avertissements de course aux données
Outils de débogage
Self._printChanges()
SwiftUI fournit une méthode de débogage uniquement pour comprendre pourquoi le corps d'une vue a été appelé.
Utilisation dans LLDB :
// Définir un point d'arrêt dans le corps de la vue
// Dans la console LLDB :
(lldb) expression Self._printChanges()
Temporaire dans le code (à supprimer avant de publier) :
var body: some View {
let _ = Self._printChanges() // Débogage uniquement
Text("Bonjour")
}
Interprétation de la sortie :
MyView: @self changed
- Signifie que la valeur de la vue elle-même a changé (paramètres passés à la vue)
MyView: count changed
- Signifie que la propriété @State "count" a déclenché la mise à jour
MyView: (aucune sortie)
- Le corps n'est pas appelé ; la vue ne se met pas du tout à jour
⚠️ Important :
- Préfixé par un trait de soulignement → Peut être supprimé dans les futures versions
- NE JAMAIS soumettre à l'App Store avec des appels à _printChanges
- Impact sur les performances → Utiliser uniquement pendant le débogage
Quand l'utiliser :
- Besoin de comprendre le déclencheur exact de la mise à jour de la vue
- Enquête sur des mises à jour inattendues
- Vérification des dépendances après un refactoring
Référence croisée : Pour les motifs de mise à jour complexes, utilisez l'instrument SwiftUI → voir la compétence axiom-swiftui-performance
Arbre de décision : La vue ne se met pas à jour
La frustration la plus courante : vous avez changé @State mais la vue ne s'est pas redessinée. La cause racine est toujours l'une des quatre choses suivantes.
Étape 1 : Pouvez-vous reproduire dans un aperçu minimal ?
#Preview {
YourView()
}
OUI → Le problème est dans votre code. Passez à l'étape 2.
NON → Il s'agit probablement de l'état Xcode ou d'une corruption de cache. Passez à la section Plantages d'aperçu.
Étape 2 : Diagnostiquer la cause racine
Cause racine 1 : Mutation de structure
Symptôme : Vous modifiez une valeur @State directement, mais la vue ne se met pas à jour.
Pourquoi cela se produit : SwiftUI ne voit pas les mutations directes sur les structures. Vous devez réaffecter la valeur entière.
// ❌ FAUX : La mutation directe ne déclenche pas de mise à jour
@State var items: [String] = []
func addItem(_ item: String) {
items.append(item) // SwiftUI ne voit pas ce changement
}
// ✅ CORRECT : La réaffectation déclenche la mise à jour
@State var items: [String] = []
func addItem(_ item: String) {
var newItems = items
newItems.append(item)
self.items = newItems // Réaffectation complète
}
// ✅ AUSSI CORRECT : Utiliser une liaison
@State var items: [String] = []
var itemsBinding: Binding<[String]> {
Binding(
get: { items },
set: { items = $0 }
)
}
Correction : Réaffectez toujours la valeur entière de la structure, pas ses parties.
Cause racine 2 : Perte d'identité de liaison
Symptôme : Vous passez une liaison à une vue enfant, mais les changements dans l'enfant ne mettent pas à jour le parent.
Pourquoi cela se produit : Vous passez .constant() ou créez une nouvelle liaison à chaque fois, cassant la connexion bidirectionnelle.
// ❌ FAUX : La liaison constante est en lecture seule
@State var isOn = false
ToggleChild(value: .constant(isOn)) // Les changements sont ignorés
// ❌ FAUX : Nouvelle liaison créée à chaque rendu
@State var name = ""
TextField("Nom", text: Binding(
get: { name },
set: { name = $0 }
)) // Nouvel objet de liaison à chaque rendu du parent
// ✅ CORRECT : Passer la liaison réelle
@State var isOn = false
ToggleChild(value: $isOn)
// ✅ CORRECT (iOS 17+) : Utiliser @Bindable pour les objets @Observable
@Observable class Book {
var title = "Exemple"
var isAvailable = true
}
struct EditView: View {
@Bindable var book: Book // Active la syntaxe $book.title
var body: some View {
TextField("Titre", text: $book.title)
Toggle("Disponible", isOn: $book.isAvailable)
}
}
// ✅ AUSSI CORRECT (iOS 17+) : @Bindable comme variable locale
struct ListView: View {
@State private var books = [Book(), Book()]
var body: some View {
List(books) { book in
@Bindable var book = book // Liaison en ligne
TextField("Titre", text: $book.title)
}
}
}
// ✅ CORRECT (pré-iOS 17) : Créer la liaison une fois, pas dans le body
@State var name = ""
@State var nameBinding: Binding<String>?
var body: some View {
if nameBinding == nil {
nameBinding = Binding(
get: { name },
set: { name = $0 }
)
}
return TextField("Nom", text: nameBinding!)
}
Correction : Passez $state directement lorsque c'est possible. Pour les objets @Observable (iOS 17+), utilisez @Bindable. Si vous créez des liaisons personnalisées (pré-iOS 17), créez-les dans init ou mettez-les en cache, pas dans body.
Cause racine 3 : Recréation accidentelle de vue
Symptôme : La vue se met à jour, mais les valeurs @State se réinitialisent à l'état initial. Vous voyez de brefs flashs des valeurs initiales.
Pourquoi cela se produit : La vue a reçu une nouvelle identité (supprimée d'un conditionnel, déplacée dans un conteneur, ou le conteneur lui-même a été recréé), ce qui amène SwiftUI à la traiter comme une nouvelle vue.
// ❌ FAUX : L'identité de la vue change lorsque la condition bascule
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter() // Obtient une nouvelle identité à chaque changement de showCounter
}
Button("Basculer") {
showCounter.toggle()
}
}
}
// Counter est recréé, @State count se remet à 0
// ✅ CORRECT : Préserver l'identité avec opacité ou masqué
@State var count = 0
var body: some View {
VStack {
Counter()
.opacity(showCounter ? 1 : 0)
Button("Basculer") {
showCounter.toggle()
}
}
}
// ✅ AUSSI CORRECT : Utiliser id() si vous devez afficher conditionnellement
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter()
.id("compteur") // Identité stable
}
Button("Basculer") {
showCounter.toggle()
}
}
}
Correction : Préservez l'identité de la vue en utilisant .opacity() au lieu de conditionnels, ou appliquez .id() avec un identifiant stable.
Cause racine 4 : Motif d'observateur manquant
Symptôme : Un objet a changé, mais les vues qui l'observent ne se sont pas mises à jour.
Pourquoi cela se produit : SwiftUI ne sait pas qu'il doit surveiller les changements dans l'objet.
// ❌ FAUX : Les changements de propriété ne déclenchent pas de mise à jour
class Model {
var count = 0 // Non observable
}
struct ContentView: View {
let model = Model() // Nouvelle instance à chaque rendu, non observable
var body: some View {
Text("\(model.count)")
Button("Incrémenter") {
model.count += 1 // La vue ne se met pas à jour
}
}
}
// ✅ CORRECT (iOS 17+) : Utiliser @Observable avec @State
@Observable class Model {
var count = 0 // Pas besoin de @Published
}
struct ContentView: View {
@State private var model = Model() // @State, pas @StateObject
var body: some View {
Text("\(model.count)")
Button("Incrémenter") {
model.count += 1 // La vue se met à jour
}
}
}
// ✅ CORRECT (iOS 17+) : Objets @Observable injectés
struct ContentView: View {
var model: Model // Juste une propriété simple
var body: some View {
Text("\(model.count)") // La vue se met à jour lorsque count change
}
}
// ✅ CORRECT (iOS 17+) : @Observable avec environnement
@Observable class AppModel {
var count = 0
}
@main
struct MyApp: App {
@State private var model = AppModel()
var body: some Scene {
WindowGroup {
ContentView()
.environment(model) // Ajouter à l'environnement
}
}
}
struct ContentView: View {
@Environment(AppModel.self) private var model // Lire depuis l'environnement
var body: some View {
Text("\(model.count)")
}
}
// ✅ CORRECT (pré-iOS 17) : Utiliser @StateObject/ObservableObject
class Model: ObservableObject {
@Published var count = 0
}
struct ContentView: View {
@StateObject var model = Model() // Pour les instances possédées
var body: some View {
Text("\(model.count)")
Button("Incrémenter") {
model.count += 1 // La vue se met à jour
}
}
}
// ✅ CORRECT (pré-iOS 17) : Utiliser @ObservedObject pour les instances injectées
struct ContentView: View {
@ObservedObject var model: Model // Passé depuis le parent
var body: some View {
Text("\(model.count)")
}
}
Correction (iOS 17+) : Utilisez la macro @Observable sur votre classe, puis @State pour la stocker. Les vues suivent automatiquement les dépendances sur les propriétés qu'elles lisent.
Correction (pré-iOS 17) : Utilisez @StateObject si vous possédez l'objet, @ObservedObject s'il est injecté, ou @EnvironmentObject s'il est partagé dans l'arbre.
Pourquoi @Observable est meilleur (iOS 17+) :
- Suivi automatique des dépendances (seules les lectures déclenchent des mises à jour)
- Pas besoin du wrapper @Published
- Fonctionne avec @State au lieu de @StateObject
- Peut être passé comme propriété simple au lieu de @ObservedObject
Voir aussi : Gestion des données de modèle dans votre application
Résumé de l'arbre de décision
digraph view_not_updating {
start [label="La vue ne se met pas à jour ?" shape=diamond];
reproduce [label="Peut-on reproduire dans l'aperçu ?" shape=diamond];
cause [label="Qu'est-ce qui a changé ?" shape=diamond];
start -> reproduce;
reproduce -> cause [label="oui : bug dans le code"];
reproduce -> "État Xcode/Cache → Plantages d'aperçu" [label="non"];
cause -> "Mutation de structure" [label="structure modifiée directement"];
cause -> "Perte d'identité de liaison" [label="liaison passée à l'enfant"];
cause -> "Recréation accidentelle" [label="vue dans un conditionnel"];
cause -> "Observateur manquant" [label="objet changé, vue inchangée"];
}
Arbre de décision : Plantages d'aperçu
Lorsque votre aperçu ne se charge pas ou plante immédiatement, les trois causes racines sont distinctes.
Étape 1 : Quelle est l'erreur ?
Type d'erreur 1 : « Cannot find in scope » ou « No such module »
Cause racine : L'aperçu manque d'une dépendance requise (@EnvironmentObject, @Environment, module importé).
// ❌ FAUX : ContentView a besoin d'un modèle, l'aperçu ne le fournit pas
struct ContentView: View {
@EnvironmentObject var model: AppModel
var body: some View {
Text(model.title)
}
}
#Preview {
ContentView() // Plante : modèle introuvable
}
// ✅ CORRECT : Fournir la dépendance
#Preview {
ContentView()
.environmentObject(AppModel())
}
// ✅ AUSSI CORRECT : Vérifier les imports manquants
// Si vous utilisez des types personnalisés, assurez-vous qu'ils sont importés dans le fichier d'aperçu
#Preview {
MyCustomView() // Assurez-vous que MyCustomView est défini ou importé
}
Correction : Suivez l'erreur, trouvez ce qui manque, fournissez-le à l'aperçu.
Type d'erreur 2 : Erreur fatale ou plantage silencieux (pas de message d'erreur)
Cause racine : L'initialisation de l'état a échoué à l'exécution. La vue a essayé d'accéder à des données qui n'existent pas.
// ❌ FAUX : Index hors limites à l'exécution
struct ListView: View {
@State var selectedIndex = 10
let items = ["a", "b", "c"]
var body: some View {
Text(items[selectedIndex]) // Plante : l'index 10 n'existe pas
}
}
// ❌ FAUX : Le déballage forcé d'optionnel échoue
struct DetailView: View {
@State var data: Data?
var body: some View {
Text(data!.title) // Plante si data est nil
}
}
// ✅ CORRECT : Valeurs par défaut sûres
struct ListView: View {
@State var selectedIndex = 0 // Index valide
let items = ["a", "b", "c"]
var body: some View {
if selectedIndex < items.count {
Text(items[selectedIndex])
}
}
}
// ✅ CORRECT : Gérer les optionnels
struct DetailView: View {
@State var data: Data?
var body: some View {
if let data = data {
Text(data.title)
} else {
Text("Aucune donnée")
}
}
}
Type d'erreur 3 : L'aperçu se charge mais reste vide ou bloqué
Cause racine : Dépendances cycliques, chargements asynchrones non gérés, ou récursion infinie due à des calculs dans body.
// ❌ FAUX : Le corps déclenche RecursiveUpdate
struct ContentView: View {
var body: some View {
MyView()
}
}
struct MyView: View {
@State var isActive = false
var body: some View {
if isActive {
ContentView() // Détection de boucle potentielle
}
}
}
// ✅ CORRECT : Éviter les cycles de vues
struct ContentView: View {
var body: some View {
MyView(isActive: $isActive)
}
}
⚠️ Important : Le #Preview de Xcode n'a pas d'état d'application complet.
Résumé de l'arbre de décision pour les plantages d'aperçu
flowchart TD
A[L'aperçu plante-t-il ?] --> B{L'erreur indique-t-elle un type ou un module manquant ?}
B -- Oui --> C[Fournir les dépendances manquantes avec .environmentObject() ou .environment()]
B -- Non --> D{Le plantage se produit-il immédiatement sans message ?}
D -- Oui --> E[Vérifier les index hors limites, les déballages forcés ou les valeurs nil]
D -- Non --> F{La vue reste-t-elle vide ou bloquée ?}
F -- Oui --> G[Vérifier les dépendances cycliques, les calculs lourds dans body ou les chargements asynchrones non gérés]
F -- Non --> H[Vider le dossier DerivedData : rm -rf ~/Library/Developer/Xcode/DerivedData]
**Correction** : Utilisez l'arbre ci-dessus pour décider de la cause racine. Si tout le reste échoue, exécutez la commande shell suivante :
```bash
rm -rf ~/Library/Developer/Xcode/DerivedData
Puis redémarrez Xcode. Cela résout la plupart des problèmes de cache.
Problèmes de mise en page
Symptôme : La vue apparaît dans la mauvaise position
Causes courantes :
- Mauvaise utilisation de l'alignement : Utilisez des alignements explicites pour les piles (VStack, HStack, ZStack).
- Marges ou espacements incorrects : Utilisez
.padding()avec des valeurs spécifiques. - Priorités de contenu : Ajustez les priorités avec
.layoutPriority().
Symptôme : La vue a la mauvaise taille
Causes courantes :
- Ignorer les géométries : Utilisez
GeometryReaderpour obtenir la taille réelle du conteneur parent. - Mauvaise utilisation de
frame: Utilisez.frame(maxWidth: .infinity)pour occuper l'espace disponible. - Aspect Ratio : Utilisez
.aspectRatio()pour maintenir les proportions.
Symptôme : Chevauchement inattendu des vues
Causes courantes :
- Mauvaise utilisation de
offset: Utiliseroffsetne modifie que la position visuelle, pas le layout. Utilisezpositionsi vous voulez changer la position dans le layout. - ZIndex : Utilisez
.zIndex()pour contrôler l'ordre de superposition dans une ZStack.
Notes sur les versions iOS
iOS 14-16
Les motifs d'observateurs sont différents : utilisez @StateObject, @ObservedObject, @EnvironmentObject.
iOS 17+
Utilisez la macro @Observable pour une gestion plus propre de l'état. Les vues mettent automatiquement à jour leurs dépendances.
Compétences connexes
- axiom-xcode-debugging : Pour les problèmes de construction, de cache et de diagnostics d'environnement.
- axiom-swift-concurrency : Pour les problèmes liés à async/await, MainActor et les courses aux données.
- axiom-swiftui-performance : Pour le profilage avec Instruments et les benchmarks de performances.
- axiom-swiftui-layout : Pour les motifs de mise en page adaptative et les géométries complexes.