Navigation SwiftUI
Quand utiliser ce skill
À utiliser lorsque :
- Vous choisissez une architecture de navigation (NavigationStack vs NavigationSplitView vs TabView)
- Vous implémentez une navigation programmatique avec NavigationPath
- Vous mettez en place des liens profonds et du routage d'URL
- Vous implémentez la restauration d'état pour la navigation
- Vous adoptez des motifs d'onglets/barre latérale (iOS 18+)
- Vous implémentez des motifs de coordinateur/routeur
- Vous demandez une revue de code de l'implémentation de navigation avant de la livrer
Compétences associées
- Utilisez
axiom-swiftui-nav-diagpour le dépannage systématique des échecs de navigation - Utilisez
axiom-swiftui-nav-refpour une référence API complète (incluant la personnalisation des onglets, fonctionnalités iOS 26+) avec tous les exemples de la WWDC
Exemples de questions
Voici des questions réelles que les développeurs posent et auxquelles ce skill est conçu pour répondre :
1. "Dois-je utiliser NavigationStack ou NavigationSplitView pour mon application ?"
-> Le skill fournit un arbre de décision basé sur les cibles d'appareil, la profondeur de la hiérarchie de contenu et les exigences multiplateformes.
2. "Comment naviguer programmatiquement dans SwiftUI ?"
-> Le skill montre les motifs de manipulation de NavigationPath pour push, pop, pop-to-root et les liens profonds.
3. "Mes liens profonds ne fonctionnent pas. L'application s'ouvre mais affiche le mauvais écran."
-> Le skill couvre les motifs d'analyse d'URL, l'ordre de construction du chemin et les problèmes de synchronisation avec onOpenURL.
4. "L'état de navigation est perdu lorsque mon application passe en arrière-plan."
-> Le skill démontre NavigationPath Codable, la persistance SceneStorage et une restauration résistante aux crashs.
5. "Comment implémenter un motif de coordinateur dans SwiftUI ?"
-> Le skill fournit des exemples de motif de routeur ainsi que des conseils sur quand les coordinateurs ajoutent de la valeur par rapport à la complexité.
Drapeaux Rouges — Anti-patrons à éviter
Si vous faites l'UN de ces éléments, ARRÊTEZ et utilisez les motifs décrits dans ce skill :
❌ CRITIQUE — Ne jamais faire ceci
1. Utiliser NavigationView dépréciée sur iOS 16+
// ❌ FAUX — Déprécié, comportement différent sur iOS 16+
NavigationView {
List { ... }
}
.navigationViewStyle(.stack)
Pourquoi cela échoue NavigationView est dépréciée depuis iOS 16. Elle ne supporte pas NavigationPath, rendant la navigation programmatique et les liens profonds peu fiables. Un comportement différent selon les versions d'iOS provoque des bugs.
2. Utiliser NavigationLink basé sur une vue pour la navigation programmatique
// ❌ FAUX — Impossible de contrôler programmatiquement
NavigationLink("Recette") {
RecipeDetail(recipe: recipe) // Destination de vue, pas de valeur
}
Pourquoi cela échoue Les liens basés sur des vues ne peuvent pas être contrôlés programmatiquement. Pas moyen d'établir un lien profond ou de revenir à cette destination. Déprécié depuis iOS 16.
3. Placer navigationDestination à l'intérieur de conteneurs paresseux
// ❌ FAUX — Peut ne pas être chargé quand nécessaire
LazyVGrid(columns: columns) {
ForEach(items) { item in
NavigationLink(value: item) { ... }
.navigationDestination(for: Item.self) { item in // Ne faites pas ceci
ItemDetail(item: item)
}
}
}
Pourquoi cela échoue Les conteneurs paresseux ne chargent pas toutes les vues immédiatement. navigationDestination peut ne pas être visible pour NavigationStack, provoquant un échec silencieux de la navigation.
4. Stocker des objets de modèle complets dans NavigationPath pour la restauration
// ❌ FAUX — Duplique les données, obsolète lors de la restauration
class NavigationModel: Codable {
var path: [Recipe] = [] // Objets Recipe complets
}
Pourquoi cela échoue Duplique les données déjà présentes dans votre modèle. Lors de la restauration, les données Recipe peuvent être obsolètes (modifiées/supprimées ailleurs). Utilisez des identifiants et résolvez selon les données actuelles.
5. Modifier NavigationPath en dehors de MainActor
// ❌ FAUX — Mise à jour UI hors thread principal
Task.detached {
await viewModel.path.append(recipe) // Thread d'arrière-plan
}
Pourquoi cela échoue NavigationPath est lié à l'UI. Les modifications doivent se faire sur MainActor sinon l'état de navigation devient corrompu. Peut provoquer des crashs ou des échecs silencieux.
6. Absence d'isolation @MainActor pour l'état de navigation
// ❌ FAUX — Non isolé @MainActor
class Router: ObservableObject {
@Published var path = NavigationPath() // Pas de @MainActor
}
Pourquoi cela échoue Avec la concurrence stricte de Swift 6, les propriétés @Published accédées depuis des vues SwiftUI nécessitent une isolation MainActor. Provoque des avertissements de course aux données et des crashs potentiels.
7. Ne pas gérer l'état de navigation dans les applications à plusieurs onglets
// ❌ FAUX — NavigationPath partagé entre les onglets
TabView {
Tab("Accueil") { HomeView() }
Tab("Paramètres") { SettingsView() }
}
// Tous les onglets partagent le même NavigationStack — faux !
Pourquoi cela échoue Chaque onglet doit avoir son propre NavigationStack pour préserver l'état de navigation lors du changement d'onglet. Un état partagé provoque une expérience utilisateur confuse.
8. Ignorer les erreurs de décodage de NavigationPath
// ❌ FAUX — Plante sur des données invalides
let path = NavigationPath(try! decoder.decode(NavigationPath.CodableRepresentation.self, from: data))
Pourquoi cela échoue L'utilisateur peut avoir supprimé des éléments qui étaient dans le chemin. Le schéma peut avoir changé. Le déballage forcé provoque un crash lors de la restauration.
Premières étapes obligatoires
Effectuez TOUJOURS ces étapes avant d'implémenter la navigation :
// Étape 1 : Identifiez votre structure de navigation
// Question : Pile unique ? Multi-colonnes ? Basé sur onglets avec navigation par onglet ?
// Notez la réponse avant d'écrire du code
// Étape 2 : Choisissez le conteneur en fonction de la structure
// Pile unique (principalement iPhone) : NavigationStack
// Multi-colonnes (principalement iPad/Mac) : NavigationSplitView
// Basé sur onglets : TabView avec NavigationStack par onglet
// Étape 3 : Définissez vos types de valeurs pour la navigation
// Toutes les valeurs poussées sur NavigationStack doivent être Hashable
// Pour les liens profonds/restauration, également Codable
struct Recipe: Hashable, Codable, Identifiable { ... }
// Étape 4 : Planifiez les URL de liens profonds (si nécessaire)
// myapp://recipe/{id}
// myapp://category/{name}/recipe/{id}
// Étape 5 : Planifiez la restauration d'état (si nécessaire)
// Allez-vous utiliser SceneStorage ? Quelles données doivent être Codable ?
Arbre de décision rapide
Besoin de navigation ?
├─ Interface multi-colonnes (principalement iPad/Mac) ?
│ └─ NavigationSplitView
│ ├─ Besoin de forer dans la colonne de détail ?
│ │ └─ NavigationStack dans le détail (Motif 3)
│ └─ Détail uniquement par sélection ?
│ └─ Juste le binding de sélection (Motif 2)
├─ Application basée sur onglets ?
│ └─ TabView
│ ├─ Chaque onglet a besoin de forage ?
│ │ └─ NavigationStack par onglet (Motif 4)
│ └─ Expérience de barre latérale iPad ?
│ └─ .tabViewStyle(.sidebarAdaptable) (Motif 5)
└─ Pile unique ?
└─ NavigationStack
├─ Besoin de liens profonds ?
│ └─ Utiliser NavigationPath (Motif 1b)
└─ Push/pop simple ?
└─ Tableau typé de chemin (Motif 1a)
Besoin de restauration d'état ?
└─ SceneStorage + NavigationPath Codable (Motif 6)
Besoin d'abstraction de coordinateur ?
├─ Flux conditionnels complexes ?
├─ Tests de logique de navigation nécessaires ?
├─ Partage de la navigation entre plusieurs écrans ?
└─ OUI à l'un → Motif de routeur (Motif 7)
NON à tous → Utiliser NavigationPath directement
Motif 1a : NavigationStack basique
Quand : Navigation push/pop simple, toutes les destinations du même type
Temps estimé : 5-10 min
struct RecipeList: View {
@State private var path: [Recipe] = []
var body: some View {
NavigationStack(path: $path) {
List(recipes) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle("Recettes")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
// Navigation programmatique
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func popToRoot() {
path.removeAll()
}
}
Points clés :
- Tableau typé
[Recipe]quand toutes les valeurs sont du même type NavigationLink(title, value:)basé sur la valeurnavigationDestination(for:)en dehors des conteneurs paresseux
Motif 1b : NavigationStack avec liens profonds
Quand : Plusieurs types de destination, liens profonds basés sur URL
Temps estimé : 15-20 min
struct ContentView: View {
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
HomeView()
.navigationDestination(for: Category.self) { category in
CategoryView(category: category)
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.onOpenURL { url in
handleDeepLink(url)
}
}
func handleDeepLink(_ url: URL) {
// URL : myapp://category/desserts/recipe/apple-pie
path.removeLast(path.count) // Revenir à la racine d'abord
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
let segments = components.path.split(separator: "/").map(String.init)
var index = 0
while index < segments.count - 1 {
switch segments[index] {
case "category":
if let category = Category(rawValue: segments[index + 1]) {
path.append(category)
}
index += 2
case "recipe":
if let recipe = dataModel.recipe(named: segments[index + 1]) {
path.append(recipe)
}
index += 2
default:
index += 1
}
}
}
}
Points clés :
NavigationPathpour les types hétérogènes- Revenir à la racine avant de construire le chemin du lien profond
- Construire le chemin dans le bon ordre (parent → enfant)
Motif 2 : NavigationSplitView basé sur la sélection
Quand : Disposition multi-colonnes où le détail affiche l'élément sélectionné
Temps estimé : 10-15 min
struct MultiColumnView: View {
@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Catégories")
} content: {
if let category = selectedCategory {
List(recipes(in: category), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle(category.name)
} else {
Text("Sélectionnez une catégorie")
}
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Sélectionnez une recette")
}
}
}
}
Points clés :
selection: $bindingsur List se connecte à la sélection de colonne- Les liens présentant des valeurs mettent automatiquement à jour la sélection
- S'adapte à une pile unique sur iPhone
Motif 3 : NavigationSplitView avec pile dans le détail
Quand : Multi-colonnes avec capacité de forage dans le détail
Temps estimé : 20-25 min
struct GridWithDrillDown: View {
@State private var selectedCategory: Category?
@State private var path: [Recipe] = []
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Catégories")
} detail: {
NavigationStack(path: $path) {
if let category = selectedCategory {
RecipeGrid(category: category)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
} else {
Text("Sélectionnez une catégorie")
}
}
}
}
}
Points clés :
- NavigationStack dans la colonne de détail
- Forage Grille → Détail tout en préservant la barre latérale
- Chemin séparé pour le forage, sélection pour la barre latérale
Motif 4 : TabView avec NavigationStack par onglet
Quand : Application basée sur onglets où chaque onglet a sa propre navigation
Temps estimé : 15-20 min
struct TabBasedApp: View {
var body: some View {
TabView {
Tab("Accueil", systemImage: "house") {
NavigationStack {
HomeView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
}
Tab("Recherche", systemImage: "magnifyingglass") {
NavigationStack {
SearchView()
}
}
Tab("Paramètres", systemImage: "gear") {
NavigationStack {
SettingsView()
}
}
}
}
}
Points clés :
- Chaque onglet a son propre NavigationStack
- L'état de navigation est préservé lors du changement d'onglet
- Syntaxe d'onglet iOS 18+ avec systemImage
Motif 5 : TabView adaptable avec barre latérale (iOS 18+)
Quand : Barre d'onglets sur iPhone, barre latérale sur iPad
Temps estimé : 20-25 min
struct AdaptableApp: View {
var body: some View {
TabView {
Tab("Regarder maintenant", systemImage: "play") {
WatchNowView()
}
Tab("Bibliothèque", systemImage: "books.vertical") {
LibraryView()
}
TabSection("Collections") {
Tab("Favoris", systemImage: "star") {
FavoritesView()
}
Tab("Récemment ajouté", systemImage: "clock") {
RecentView()
}
}
Tab(role: .search) {
SearchView()
}
}
.tabViewStyle(.sidebarAdaptable)
}
}
Points clés :
.tabViewStyle(.sidebarAdaptable)active la barre latérale sur iPadTabSectioncrée des groupes repliables dans la barre latéraleTab(role: .search)obtient un placement spécial
Motif 6 : Restauration d'état
Quand : L'utilisateur s'attend à reprendre exactement là où il s'est arrêté après avoir quitté l'application
Temps estimé : 20-30 min
struct ContentView: View {
@SceneStorage("navigationState") private var navigationStateData: Data?
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
HomeView()
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.onAppear {
restorePath()
}
.onChange(of: path.codable) { _, newValue in
savePath(newValue)
}
}
private func restorePath() {
guard let data = navigationStateData else { return }
guard let codable = try? JSONDecoder().decode(
NavigationPath.CodableRepresentation.self,
from: data
) else { return }
path = NavigationPath(codable)
}
private func savePath(_ codable: NavigationPath.CodableRepresentation?) {
guard let codable = codable else {
navigationStateData = nil
return
}
navigationStateData = try? JSONEncoder().encode(codable)
}
}
Points clés :
SceneStoragelie la persistance de l'état au cycle de vie de la scènepath.codableconvertit NavigationPath en représentation encodable (iOS 17+)- Les échecs de décodage sont gérés silencieusement — restaure un chemin vide plutôt que de planter
- Aucune manipulation directe de UserDefaults — SceneStorage gère la sérialisation automatiquement
- Sur iOS 16, utilisez
CodableNavigationPathpersonnalisé ou des types de chemin génériques
Motif 7 : Modèle de routeur
Quand : Logique de navigation complexe nécessitant abstraction et testabilité
Temps estimé : 30-45 min
@MainActor
@Observable
final class Router {
var path = NavigationPath()
private let dataModel: DataModel
init(dataModel: DataModel) {
self.dataModel = dataModel
}
func navigateToRecipe(_ id: Recipe.ID) {
guard let recipe = dataModel.recipe(id: id) else { return }
path.append(recipe)
}
func navigateToCategory(_ category: Category) {
path.removeLast(path.count)
path.append(category)
}
func handleDeepLink(_ url: URL) {
path.removeLast(path.count)
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
let segments = components.path.split(separator: "/").map(String.init)
// ... logique de construction de chemin
}
func reset() {
path.removeLast(path.count)
}
}
// Exemple d'utilisation dans une vue
struct ContentView: View {
@State private var router = Router(dataModel: .shared)
var body: some View {
NavigationStack(path: $router.path) {
HomeView()
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.environment(router)
.onOpenURL { router.handleDeepLink($0) }
}
}
Points clés :
@MainActorisolé (Swift 6)@Observablepour les mises à jour de vue SwiftUI- Toute la logique de navigation centralisée dans un seul objet
- Les destins sont résolus via des identifiants (pas de données en double)
- Testable : injectez des modèles simulés, vérifiez les changements de chemin
Piège courant : Identifiants encodés
Quand : Les données dans NavigationPath ne peuvent pas être rendues Codable directement (par exemple, classes, types complexes)
Temps estimé : 10-15 min de débogage évité
// ⚠️ Codable opaque uniquement sur iOS 17+
// Solution : stocker des identifiants, référencer les données courantes
struct NavigationID: Hashable, Codable {
let type: String
let id: String
}
// Utilisation dans le routeur
path.append(NavigationID(type: "recipe", id: recipe.id))
Points clés :
- Ne jamais stocker d'objets complets dans le chemin de navigation
- Stockez des références légères (identifiants) et résolvez les données à l'affichage
- Plus facile à tester, moins de bugs de sérialisation
Piège courant : NavigationView sur iOS 16+
Quand : Code hérité utilisant NavigationView doit être mis à jour
Temps estimé : 15-30 min de migration
// AVANT (iOS 15)
struct OldView: View {
var body: some View {
NavigationView {
List { ... }
Text("Détail")
}
}
}
// APRÈS (iOS 16+)
struct NewView: View {
var body: some View {
NavigationSplitView { // Ou NavigationStack pour pile unique
List { ... }
} detail: {
Text("Détail")
}
}
}
Points clés :
- NavigationView est complètement dépréciée sur iOS 16+
- Migration vers NavigationSplitView pour la disposition multi-colonnes
- Migration vers NavigationStack pour la disposition à pile unique
- .navigationViewStyle n'existe pas sur les nouveaux conteneurs
- Les nouvelles API offrent une bien meilleure programmabilité
Questions courantes
Q : Quelle est la différence entre NavigationPath et un tableau typé ?
R : NavigationPath accepte n'importe quel type Hashable, permettant des piles hétérogènes (par exemple, [Recette, Auteur, Commentaire]). Les tableaux typés ([Recette]) sont plus sûrs et plus faciles à déboguer. Utilisez NavigationPath uniquement lorsque des types multiples sont nécessaires ou pour la compatibilité avec Codable.
Q : Comment gérer les liens profonds dans une TabView ? R : Chaque onglet doit avoir son propre gestionnaire de liens profonds. Analysez l'URL pour déterminer l'onglet cible et le chemin de navigation. Utilisez la liaison binding de sélection d'onglet pour programmer l'onglet actif avant d'appliquer le chemin.
Q : Les NavigationStacks peuvent-ils être imbriqués ? R : Évitez les NavigationStacks imbriqués. Un seul contrôleur de navigation par pile. Utilisez des feuilles (sheets) ou d'autres présentations modales pour la navigation secondaire.
Q : Comment tester la logique de navigation ? R : Utilisez un modèle de routeur (Motif 7) pour isoler la logique de navigation. Testez les transitions de chemin avec des identifiants simulés. Vérifiez que les chemins sont corrects après les actions utilisateur ou les liens profonds.