Diagnostics de Navigation SwiftUI
Aperçu
Principe fondamental : 85 % des problèmes de navigation proviennent d'erreurs de gestion de l'état du chemin, de problèmes d'identité de vue ou d'erreurs de placement, et non de défauts de SwiftUI.
Le système de navigation de SwiftUI est utilisé par des millions d'applications et gère de manière fiable des schémas de navigation complexes. Si votre navigation échoue, ne répond pas ou se comporte de manière inattendue, le problème vient presque toujours de la façon dont vous gérez l'état de la navigation, et non du framework lui-même.
Cette compétence fournit des diagnostics systématiques pour identifier les causes profondes en quelques minutes, et non en plusieurs heures.
Signaux d'alarme — Suspectez un problème de navigation
Si vous voyez l'UN de ces symptômes, suspectez un problème de code, pas une rupture du framework :
-
Un appui sur la navigation ne fait rien (le lien est présent mais ne pousse pas)
-
Le bouton retour revient à un écran incorrect ou à la racine
-
Un lien profond ouvre l'application mais affiche le mauvais écran
-
L'état de navigation est perdu lors du changement d'onglet
-
L'état de navigation est perdu lorsque l'application passe en arrière-plan
-
Un même NavigationLink pousse deux fois
-
L'animation de navigation est bloquée ou saccadée
-
Plantage avec
navigationDestinationdans la trace de la pile -
❌ INTERDIT "La navigation SwiftUI est cassée, enveloppons-la avec UINavigationController"
- NavigationStack est utilisé par les propres applications d'Apple
- Envelopper UIKit ajoute de la complexité et perd les avantages de la gestion d'état de SwiftUI
- L'interopérabilité avec UIKit a ses propres cas particuliers que vous passerez des semaines à découvrir
- Votre problème est presque certainement une gestion de chemin, pas un défaut du framework
Distinction critique : Le comportement de NavigationStack est déterministe. S'il ne fonctionne pas, vous modifiez l'état de manière incorrecte, vous avez des problèmes d'identité de vue, ou navigationDestination est mal placé.
Premières étapes obligatoires
Exécutez TOUJOURS ces vérifications en premier (avant de modifier le code) :
// 1. Ajouter la journalisation de NavigationPath
NavigationStack(path: $path) {
RootView()
.onChange(of: path.count) { oldCount, newCount in
print("📍 Chemin changé : \(oldCount) → \(newCount)")
// Si cela ne se déclenche jamais, le lien ne modifie pas le chemin
// Si cela se déclenche de manière inattendue, autre chose modifie le chemin
}
}
// 2. Vérifier que navigationDestination est visible
// Mettre une impression temporaire dans la fermeture de destination
.navigationDestination(for: Recipe.self) { recipe in
let _ = print("🔗 Destination pour Recipe : \(recipe.name)")
RecipeDetail(recipe: recipe)
}
// Si cela ne s'imprime jamais, la destination n'est pas évaluée
// 3. Vérifier que NavigationLink est à l'intérieur de NavigationStack
// Inspection visuelle : Tracez depuis NavigationLink dans la hiérarchie des vues
// Doit atteindre NavigationStack, et non un autre conteneur en premier
// 4. Vérifier l'emplacement de l'état du chemin
// @State doit être dans une vue stable (pas recréée à chaque rendu)
// Doit être @State, @StateObject ou @Observable — pas une variable locale
// 5. Tester le cas de base isolément
// Créer une reproduction minimale
NavigationStack {
NavigationLink("Test", value: "test")
.navigationDestination(for: String.self) { str in
Text("Poussé : \(str)")
}
}
// Si cela fonctionne, le problème vient de votre configuration spécifique
Ce que cela vous indique
| Observation | Diagnostic | Prochaine étape |
|---|---|---|
| onChange ne se déclenche jamais lors d'un appui | NavigationLink pas dans la hiérarchie NavigationStack | Pattern 1a |
| onChange se déclenche mais la vue ne pousse pas | navigationDestination introuvable/non chargée | Pattern 1b |
| onChange se déclenche, la vue pousse, puis pop immédiatement | Problème d'identité de vue ou modification du chemin | Pattern 2a |
| Le chemin change de manière inattendue (pas à cause d'un appui) | Code externe modifiant le chemin | Pattern 2b |
| path.append() d'un lien profond ne navigue pas | Problème de synchronisation ou mauvais thread | Pattern 3b |
| État perdu lors du changement d'onglet | NavigationStack partagé entre les onglets | Pattern 4a |
| Fonctionne la première fois, échoue au retour | Problème de recréation de vue | Pattern 5a |
INTERPRÉTATION OBLIGATOIRE
Avant de modifier le MOINDRE code, identifiez l'UN de ces éléments :
- Si un appui sur un lien ne fait rien ET aucun onChange → Lien en dehors de NavigationStack (vérifiez la hiérarchie)
- Si onChange se déclenche mais rien ne pousse → navigationDestination hors de portée (vérifiez l'emplacement)
- Si une vue pousse puis pop immédiatement → Changement d'identité de vue ou réinitialisation du chemin (vérifiez l'emplacement de @State)
- Si un lien profond échoue → Problème de synchronisation ou de MainActor (vérifiez le thread)
- En cas de plantage → Déballage forcé sur le décodage du chemin ou enregistrement de type manquant
Si les diagnostics sont contradictoires ou peu clairs
- ARRÊTEZ. N'appliquez pas encore les modèles
- Ajoutez des instructions d'impression à chaque point de modification du chemin
- Créez un cas de reproduction minimal
- Testez d'abord avec des valeurs String (cas le plus simple)
Arbre de décision
Utilisez ceci pour atteindre le modèle de diagnostic correct en 2 minutes :
Problème de navigation ?
├─ Un appui sur la navigation ne fait rien ?
│ ├─ NavigationLink à l'intérieur de NavigationStack ?
│ │ ├─ Non → Pattern 1a (Lien en dehors de la pile)
│ │ └─ Oui → Vérifier navigationDestination
│ │
│ ├─ navigationDestination enregistré ?
│ │ ├─ Dans un conteneur paresseux ? → Pattern 1b (Chargement paresseux)
│ │ ├─ Incompatibilité de type ? → Pattern 1c (Enregistrement de type)
│ │ └─ Bloqué par sheet/popover ? → Pattern 1d (Blocage modal)
│ │
│ └─ Utilisation d'un lien basé sur une vue ?
│ └─ → Pattern 1e (API obsolète)
│
├─ Retour inattendu (pop) ?
│ ├─ Pop immédiat après poussée ?
│ │ ├─ Le corps de la vue recrée le chemin ? → Pattern 2a (Recréation du chemin)
│ │ ├─ @State dans la mauvaise vue ? → Pattern 2a (Emplacement de l'état)
│ │ └─ L'identifiant ForEach change ? → Pattern 2c (Changement d'identité)
│ │
│ ├─ Pop alors que cela ne devrait pas ?
│ │ ├─ Code externe appelant removeLast ? → Pattern 2b (Modification inattendue)
│ │ ├─ Tâche annulée ? → Pattern 2b (Annulation asynchrone)
│ │ └─ Problème de MainActor ? → Pattern 2d (Threading)
│ │
│ └─ Comportement du bouton retour incorrect ?
│ └─ → Pattern 2e (Corruption de pile)
│
├─ Lien profond ne fonctionne pas ?
│ ├─ URL non reçue ?
│ │ ├─ onOpenURL non appelé ? → Vérifiez le schéma d'URL dans Info.plist
│ │ └─ Problème de liens universels ? → Vérifiez apple-app-site-association
│ │
│ ├─ URL reçue, chemin non mis à jour ?
│ │ ├─ path.append pas sur MainActor ? → Pattern 3a (Threading)
│ │ ├─ Problème de synchronisation (application pas prête) ? → Pattern 3b (Initialisation)
│ │ └─ NavigationStack pas encore créé ? → Pattern 3b (Cycle de vie)
│ │
│ └─ Chemin mis à jour, mauvais écran affiché ?
│ ├─ Ordre de chemin incorrect ? → Pattern 3c (Construction du chemin)
│ ├─ Mauvais type ajouté ? → Pattern 3c (Incompatibilité de type)
│ └─ Élément introuvable ? → Pattern 3d (Résolution de données)
│
├─ État perdu ?
│ ├─ Perdu lors du changement d'onglet ?
│ │ ├─ NavigationStack partagé ? → Pattern 4a (État partagé)
│ │ └─ Recréation d'onglet ? → Pattern 4a (Identité d'onglet)
│ │
│ ├─ Perdu lors du passage en arrière-plan/premier plan ?
│ │ ├─ Pas de SceneStorage ? → Pattern 4b (Absence de persistance)
│ │ └─ Échec de décodage ? → Pattern 4c (Erreur de décodage)
│ │
│ └─ Perdu lors de la rotation/du changement de taille ?
│ └─ → Pattern 4d (Recréation de mise en page)
│
├─ Problème de NavigationSplitView ?
│ ├─ Barre latérale non visible sur iPad ?
│ │ ├─ columnVisibility non défini ? → Pattern 6a (Visibilité des colonnes)
│ │ └─ Classe de taille compacte ? → Pattern 6a (Adaptation automatique)
│ │
│ ├─ Détail affiché vide sur iPad ?
│ │ ├─ Pas de vue de détail par défaut ? → Pattern 6b (Détail manquant)
│ │ └─ Liaison de sélection nulle ? → Pattern 6b (État de sélection)
│ │
│ └─ Fonctionne sur iPhone, cassé sur iPad ?
│ └─ → Pattern 6c (Adaptation à la plateforme)
│
└─ Plantage ?
├─ EXC_BAD_ACCESS dans le code de navigation ?
│ └─ → Pattern 5a (Problème de mémoire)
│
├─ Erreur fatale : type non enregistré ?
│ └─ → Pattern 5b (Destination manquante)
│
└─ Échec de décodage lors de la restauration ?
└─ → Pattern 5c (Plantage de restauration)
Règles de sélection des modèles (OBLIGATOIRE)
Avant de passer à un modèle :
- Un appui sur la navigation ne fait rien → Ajoutez la journalisation onChange EN PREMIER, puis Pattern 1
- Pop inattendu → Trouvez CE qui modifie le chemin (journalisation), puis Pattern 2
- Lien profond échoue → Vérifiez que l'URL est reçue (print dans onOpenURL), puis Pattern 3
- État perdu → Identifiez QUAND il est perdu (changement d'onglet vs arrière-plan), puis Pattern 4
- Plantage → Obtenez la trace de pile complète, puis Pattern 5
Appliquez UN modèle à la fois
- Implémentez le correctif d'un seul modèle
- Testez minutieusement
- Si le problème persiste seulement, essayez le modèle suivant
- N'appliquez PAS plusieurs modèles simultanément (vous ne pouvez pas isoler la cause)
INTERDIT
- Deviner des solutions sans diagnostics
- Modifier plusieurs choses à la fois
- Envelopper avec UINavigationController "parce que SwiftUI est cassé"
- Ajouter des retards/DispatchQueue.main.async sans comprendre pourquoi
- Passer à NavigationLink basé sur une vue "pour éviter les problèmes de chemin"
Modèles de diagnostic
Modèle 1a : NavigationLink en dehors de NavigationStack
Coût en temps 5 à 10 minutes
Symptôme
- Appuyer sur NavigationLink ne fait rien
- Aucune navigation ne se produit, aucune erreur
- onChange(of: path) ne se déclenche jamais
Diagnostic
// Vérifier la hiérarchie des vues — NavigationLink doit être à L'INTÉRIEUR de NavigationStack
// ❌ MAUVAIS — Lien en dehors de la pile
struct ContentView: View {
var body: some View {
VStack {
NavigationLink("Aller", value: "test") // Hors de la pile !
NavigationStack {
Text("Racine")
}
}
}
}
// Vérifier : Ajoutez une couleur d'arrière-plan à NavigationStack
NavigationStack {
Color.red // Si le lien est sur rouge, il est à l'intérieur
}
Correctif
// ✅ CORRECT — Lien à l'intérieur de la pile
struct ContentView: View {
var body: some View {
NavigationStack {
VStack {
NavigationLink("Aller", value: "test") // À l'intérieur de la pile
Text("Racine")
}
.navigationDestination(for: String.self) { str in
Text("Poussé : \(str)")
}
}
}
}
Vérification
- Appuyez sur le lien, la navigation se produit
- onChange(of: path) se déclenche lors de l'appui
Modèle 1b : navigationDestination dans un conteneur paresseux
Coût en temps 10 à 15 minutes
Symptôme
- L'appui sur NavigationLink ne fait rien OU fonctionne par intermittence
- onChange se déclenche (chemin mis à jour) mais la vue ne pousse pas
- La console peut afficher : "A navigationDestination for [Type] was not found"
Diagnostic
// ❌ MAUVAIS — Destination dans un conteneur paresseux (peut ne pas être chargée)
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // Peut ne pas être évaluée !
}
}
}
}
Correctif
// ✅ CORRECT — Destination en dehors du conteneur paresseux
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // Toujours disponible
}
Vérification
- Ajoutez print dans la fermeture de destination — doit toujours s'imprimer lors de la navigation
- Fonctionne quelle que soit la position de défilement
Modèle 1c : Incompatibilité d'enregistrement de type
Coût en temps 10 minutes
Symptôme
- L'appui sur la navigation ne fait rien
- Aucune navigationDestination correspondante pour le type de valeur
- Peut fonctionner pour certains liens, pas pour d'autres
Diagnostic
// Vérifier : Le type de valeur doit correspondre EXACTEMENT au type de destination
// Le lien utilise Recipe
NavigationLink(recipe.name, value: recipe) // value est Recipe
// Destination enregistrée pour... Recipe.ID ?
.navigationDestination(for: Recipe.ID.self) { id in // ❌ Mauvais type !
RecipeDetail(id: id)
}
Correctif
// Faire correspondre les types exactement
NavigationLink(recipe.name, value: recipe) // Recipe
.navigationDestination(for: Recipe.self) { recipe in // ✅ Recipe
RecipeDetail(recipe: recipe)
}
// OU changer le lien pour utiliser l'ID
NavigationLink(recipe.name, value: recipe.id) // Recipe.ID
.navigationDestination(for: Recipe.ID.self) { id in // ✅ Recipe.ID
RecipeDetail(id: id)
}
Vérification
- Imprimez le type dans la destination :
print(type(of: value)) - Les types doivent correspondre exactement (pas d'héritage)
Modèle 2a : NavigationPath recréé à chaque rendu
Coût en temps 15 à 20 minutes
Symptôme
- La navigation pousse puis revient immédiatement (pop)
- La vue de destination semble "clignoter"
- Fonctionne une fois, puis échoue, ou échoue immédiatement
Diagnostic
// ❌ MAUVAIS — Chemin créé dans le corps de la vue (réinitialisé à chaque rendu)
struct ContentView: View {
var body: some View {
let path = NavigationPath() // Recréé à chaque fois !
NavigationStack(path: .constant(path)) {
// ...
}
}
}
// ❌ MAUVAIS — @State dans une vue enfant qui est recréée
struct ParentView: View {
@State var showChild = true
var body: some View {
if showChild {
ChildView() // Recréé lorsque showChild est basculé
}
}
}
struct ChildView: View {
@State var path = NavigationPath() // Perdu lorsque ChildView est recréé
// ...
}
Correctif
// ✅ CORRECT — @State à un niveau stable
struct ContentView: View {
@State private var path = NavigationPath() // Persiste entre les rendus
var body: some View {
NavigationStack(path: $path) {
RootView()
}
}
}
// ✅ CORRECT — @StateObject pour ObservableObject
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
var body: some View {
NavigationStack(path: $navModel.path) {
RootView()
}
}
}
Vérification
- Ajoutez la journalisation onChange — le chemin ne doit pas se réinitialiser de manière inattendue
- Naviguez, attendez, path.count reste stable
Modèle 2d : Chemin modifié en dehors de MainActor
Coût en temps 10 à 15 minutes
Symptôme
- La navigation fonctionne parfois, échoue à d'autres moments
- Avertissements Swift 6 concernant l'isolation MainActor
- Pops inattendus ou corruption d'état
Diagnostic
// ❌ MAUVAIS — Modification du chemin depuis une tâche en arrière-plan
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ⚠️ Pas sur MainActor !
}
// Vérifier : Recherchez path.append, path.removeLast en dehors du contexte @MainActor
Correctif
// ✅ CORRECT — Assurer MainActor
@MainActor
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ✅ Isolé MainActor
}
// OU distribuer explicitement
func loadAndNavigate() async {
let recipe = await fetchRecipe()
await MainActor.run {
path.append(recipe)
}
}
// ✅ MEILLEUR — Utiliser @Observable avec @ObservationTracked
Vérification
- La navigation fonctionne de manière cohérente
- Aucun avertissement MainActor dans le code de navigation
Modèle 4c : Échec du décodage de NavigationPath
Coût en temps 15 à 20 minutes
Symptôme
- L'état de navigation est perdu lors de la mise en arrière-plan
- Plantage lors de la restauration de l'état
- "Fatal error: try! encountered decoding error"
Diagnostic
// ❌ MAUVAIS — Types non encodables dans NavigationPath
// NavigationPath nécessite que tous les types soient Codable
NavigationStack(path: $path) {
RootView()
}
// Si un type non-Codable est ajouté, le décodage échoue
// Vérifier : Imprimez les types de chemin
print("Types dans le chemin :", path.codable.map { $0 }) // Peut être nil si non Codable
Correctif
// ✅ CORRECT — Assurer que tous les types de valeurs de navigation sont Codable
struct Recipe: Hashable, Codable {
let id: Int
let name: String
}
// OU gérer le décodage de manière sécurisée avec SceneStorage
@SceneStorage("navigationPath") private var pathData: Data = Data()
var body: some View {
let path = decodePath(from: pathData)
NavigationStack(path: Binding(get: { path }, set: { pathData = encodePath($0) })) {
// ...
}
}
func decodePath(from data: Data) -> NavigationPath {
guard let decoded = try? JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data) else {
return NavigationPath()
}
return NavigationPath(decoded)
}
func encodePath(_ path: NavigationPath) -> Data {
guard let codable = path.codable else { return Data() }
return (try? JSONEncoder().encode(codable)) ?? Data()
}
Vérification
- Naviguez, mettez en arrière-plan, restaurez — l'état est conservé
- Aucun plantage lors du décodage
Modèle 4d : Recréation de mise en page
Coût en temps 10 à 15 minutes
Symptôme
- L'état de navigation est perdu lors de la rotation ou du changement de classe de taille
- Fonctionne en portrait, échoue en paysage (ou vice versa)
- État réinitialisé quand l'application change de fenêtre
Diagnostic
// ❌ MAUVAIS — @State dans une vue qui est recréée lors d'un changement de mise en page
struct ContentView: View {
@State private var path = NavigationPath() // Perdu si ContentView est recréé
@Environment(\.horizontalSizeClass) var sizeClass
var body: some View {
if sizeClass == .regular {
NavigationSplitView {
Sidebar()
} detail: {
Detail()
}
} else {
NavigationStack(path: $path) {
Content()
}
}
}
}
Correctif
// ✅ CORRECT — Conserver l'état en dehors de la vue avec un changement de mise en page
class NavigationStateManager: ObservableObject {
@Published var path = NavigationPath()
}
struct ContentView: View {
@StateObject private var navManager = NavigationStateManager()
@Environment(\.horizontalSizeClass) var sizeClass
var body: some View {
if sizeClass == .regular {
NavigationSplitView {
Sidebar()
} detail: {
Detail()
}
} else {
NavigationStack(path: $navManager.path) {
Content()
}
}
}
}
Vérification
- Tournez l'appareil — l'état de navigation est conservé
- Changez de fenêtre (iPad) — l'état reste intact