Référence de l'API de Navigation SwiftUI
Aperçu
Les API de navigation de SwiftUI fournissent une navigation pilotée par les données et programmatique qui s'adapte des piles simples aux mises en page multi-colonnes complexes. Introduites dans iOS 16 (2022) avec NavigationStack et NavigationSplitView, elles ont évolué dans iOS 18 (2024) avec l'unification Tab/Sidebar, et ont été affinées dans iOS 26 (2025) avec le design Liquid Glass.
Chronologie de l'évolution
- 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basé sur une valeur
- 2024 (iOS 18) Unification Tab/Sidebar, style sidebarAdaptable, transition de zoom de navigation
- 2025 (iOS 26) Chrome de navigation Liquid Glass, recherche alignée en bas, barres d'onglets flottantes, backgroundExtensionEffect
Capacités clés
- Navigation pilotée par les données NavigationPath représente l'état de la pile, permettant le push/pop programmatique et le deep linking
- Mises en page multi-colonnes NavigationSplitView s'adapte automatiquement (3 colonnes sur iPad → pile unique sur iPhone)
- Restauration d'état NavigationPath Codable + SceneStorage pour la persistance entre les lancements d'applications
- Intégration des onglets NavigationStack par onglet avec préservation de l'état lors du changement d'onglet (iOS 18+)
- Liquid Glass Barres de navigation, barres latérales et barres d'outils en verre automatiques (iOS 26+)
Quand utiliser vs UIKit
- Navigation SwiftUI Nouvelles applications, multiplateforme, flux de navigation plus simples → Utiliser NavigationStack/SplitView
- UINavigationController Patterns de coordinateur complexes, code hérité, fonctionnalités UIKit spécifiques → Envisager UIKit
Compétences connexes
- Utilisez
axiom-swiftui-navpour les anti-patrons, les arbres de décision, les scénarios de pression - Utilisez
axiom-swiftui-nav-diagpour le dépannage systématique des problèmes de navigation
Quand Utiliser Cette Compétence
Utilisez cette compétence lorsque :
- Vous implémentez des API de navigation NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
- Deep linking ou restauration d'état Routage d'URL, NavigationPath Codable, SceneStorage
- Adoption de fonctionnalités iOS 26+ Navigation Liquid Glass, recherche alignée en bas, minimisation de la barre d'onglets
- Choix d'une architecture de navigation Pile vs SplitView vs patterns de coordinateur
Évolution de l'API
Chronologie
| Année | Version iOS | Fonctionnalités clés |
|---|---|---|
| 2020 | iOS 14 | NavigationView (dépréciée iOS 16) |
| 2022 | iOS 16 | NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basé sur une valeur |
| 2024 | iOS 18 | Unification Tab/Sidebar, sidebarAdaptable, TabSection, transitions de zoom |
| 2025 | iOS 26 | Navigation Liquid Glass, backgroundExtensionEffect, tabBarMinimizeBehavior |
NavigationView (Dépréciée)
NavigationView est dépréciée depuis iOS 16. Utilisez NavigationStack (push/pop à colonne unique) ou NavigationSplitView (multi-colonnes) exclusivement dans le nouveau code. Améliorations clés : un seul NavigationPath remplace les liaisons isActive par lien, sécurité de type basée sur une valeur, restauration d'état Codable intégrée. Voir la documentation « Migration vers les nouveaux types de navigation ».
Référence Complète de NavigationStack
NavigationStack représente une interface push-pop comme Réglages sur iPhone ou Préférences Système sur macOS.
1.1 Création de NavigationStack
NavigationStack de base
NavigationStack {
List(Category.allCases) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Catégories")
.navigationDestination(for: Category.self) { category in
CategoryDetail(category: category)
}
}
Avec liaison de chemin (WWDC 2022, 6:05)
struct PushableStack: View {
@State private var path: [Recipe] = []
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationStack(path: $path) {
List(Category.allCases) { category in
Section(category.localizedName) {
ForEach(dataModel.recipes(in: category)) { recipe in
NavigationLink(recipe.name, value: recipe)
}
}
}
.navigationTitle("Catégories")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.environmentObject(dataModel)
}
}
La liaison de chemin + NavigationLink présentant une valeur + navigationDestination(for:) forment le modèle de navigation pilotée par les données de base.
1.2 NavigationLink (Basé sur une Valeur)
NavigationLink présentant une valeur
// Correct : Basé sur une valeur (iOS 16+)
NavigationLink(recipe.name, value: recipe)
// Correct : Avec étiquette personnalisée
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
// Déprécié : Basé sur une vue (iOS 13-15)
NavigationLink(recipe.name) {
RecipeDetail(recipe: recipe) // Ne pas utiliser dans le nouveau code
}
Comment fonctionne NavigationLink avec NavigationStack
- NavigationStack maintient une collection
path - Appuyer sur un lien présentant une valeur ajoute la valeur au
path - NavigationStack applique les modificateurs
navigationDestinationsur les valeurs du chemin - Les vues sont poussées sur la pile en fonction des mappages de destination
1.3 Modificateur navigationDestination
Type unique
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
Types multiples
NavigationStack(path: $path) {
RootView()
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
.navigationDestination(for: Category.self) { category in
CategoryList(category: category)
}
.navigationDestination(for: Chef.self) { chef in
ChefProfile(chef: chef)
}
}
Anti-patrons de navigation
- Ne mélangez jamais
navigationDestination(for:)etNavigationLink(destination:)dans la même hiérarchie NavigationStack — provoque un comportement indéfini - Enregistrez
navigationDestination(for:)une fois par type de données — les doublons font apparaître la mauvaise vue
Règles de placement
- Placez
navigationDestinationen dehors des conteneurs paresseux (pas à l'intérieur de ForEach) - Placez-le près des NavigationLinks associés pour l'organisation du code
- Doit être à l'intérieur de la hiérarchie NavigationStack
// Correct : En dehors du conteneur paresseux
ScrollView {
LazyVGrid(columns: columns) {
ForEach(recipes) { recipe in
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
}
}
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
// Incorrect : À l'intérieur de ForEach (peut ne pas être chargé)
ForEach(recipes) { recipe in
NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
.navigationDestination(for: Recipe.self) { r in // Ne faites pas cela
RecipeDetail(recipe: r)
}
}
1.4 NavigationPath
NavigationPath est une collection à effacement de type pour des piles de navigation hétérogènes.
Tableau typé vs NavigationPath
// Tableau typé : Toutes les valeurs du même type
@State private var path: [Recipe] = []
// NavigationPath : Types mixtes
@State private var path = NavigationPath()
Opérations NavigationPath
// Ajouter une valeur
path.append(recipe)
// Revenir à la précédente
path.removeLast()
// Revenir à la racine
path.removeLast(path.count)
// ou
path = NavigationPath()
// Vérifier le nombre
if path.count > 0 { ... }
// Lien profond : Définir plusieurs valeurs
path.append(category)
path.append(recipe)
Support Codable
// NavigationPath est Codable lorsque toutes les valeurs sont Codable
@State private var path = NavigationPath()
// Encoder
let data = try JSONEncoder().encode(path.codable)
// Décoder
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)
Référence Complète de NavigationSplitView
NavigationSplitView crée des mises en page multi-colonnes qui s'adaptent à la taille de l'appareil.
2.1 Mise en page à Deux Colonnes
Mise en page à Deux Colonnes de Base (WWDC 2022, 10:40)
struct MultipleColumns: View {
@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
.navigationTitle("Catégories")
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Sélectionnez une recette")
}
}
}
}
2.2 Mise en page à Trois Colonnes
Ajoutez une closure content: entre la barre latérale et le détail pour une colonne du milieu :
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
} content: {
List(dataModel.recipes(in: selectedCategory), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
} detail: {
RecipeDetail(recipe: selectedRecipe)
}
2.3 NavigationSplitView avec NavigationStack
Placez un NavigationStack(path:) à l'intérieur de la colonne de détail pour un drill-down grille-à-détail tout en préservant la sélection de la barre latérale :
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
NavigationStack(path: $path) {
RecipeGrid(category: selectedCategory)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
2.4 Visibilité des colonnes
@State private var columnVisibility: NavigationSplitViewVisibility = .all
NavigationSplitView(columnVisibility: $columnVisibility) {
Sidebar()
} content: {
Content()
} detail: {
Detail()
}
// Contrôler la visibilité par programme
columnVisibility = .detailOnly // Masquer la barre latérale et le contenu
columnVisibility = .all // Afficher toutes les colonnes
columnVisibility = .automatic // Le système décide
2.5 Adaptation automatique
NavigationSplitView s'adapte automatiquement :
- iPad paysage Toutes les colonnes visibles (selon la configuration)
- iPad portrait/Slide Over Se réduit à une superposition ou une seule colonne
- iPhone Pile de navigation unique
- Apple Watch/TV Pile de navigation unique
Les changements de sélection se traduisent automatiquement en push/pop sur iPhone.
2.6 iOS 26+ Barre latérale Liquid Glass (WWDC 2025, 323)
NavigationSplitView {
List { ... }
} detail: {
DetailView()
}
// La barre latérale obtient automatiquement l'apparence Liquid Glass sur iPad/macOS
// Étendre le contenu derrière la barre latérale en verre
.backgroundExtensionEffect() // Miroite et floute le contenu en dehors de la zone de sécurité
Liens Profonds et Routage d'URL
3.1 Modèle de Lien Profond
Utilisez .onOpenURL pour recevoir les URL, analysez avec URLComponents, puis manipulez NavigationPath :
.onOpenURL { url in
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let host = components.host else { return }
path.removeLast(path.count) // Revenir à la racine d'abord
// Analyser l'hôte/chemin pour déterminer la destination, puis path.append(valeur)
}
Pour les liens profonds en plusieurs étapes (myapp://category/desserts/recipe/apple-pie), parcourez les composants du chemin de l'URL et ajoutez chaque valeur résolue pour construire la pile de navigation complète.
Pour des exemples complets de liens profonds, de diagnostic d'erreur et de workflows de test, voir axiom-swiftui-nav-diag (Pattern 3).
Restauration d'État
4.1 Restauration d'État Complète (WWDC 2022, 18:12)
struct UseSceneStorage: View {
@StateObject private var navModel = NavigationModel()
@SceneStorage("navigation") private var data: Data?
@StateObject private var dataModel = DataModel()
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $navModel.selectedCategory) { category in
NavigationLink(category.localizedName, value: category)
}
.navigationTitle("Catégories")
} detail: {
NavigationStack(path: $navModel.recipePath) {
RecipeGrid(category: navModel.selectedCategory)
}
}
.task {
// Restaurer à l'apparition
if let data = data {
navModel.jsonData = data
}
// Enregistrer lors des changements
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
.environmentObject(dataModel)
}
}
4.2 NavigationModel Codable
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds // Stocker les IDs, pas les objets complets
}
func encode(to encoder: Encoder) throws {
var container = encoder.container(keyedBy: CodingKeys.self)
try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
try container.encode(recipePath.map(\.id), forKey: .recipePathIds)
}
init() {}
required init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
self.selectedCategory = try container.decodeIfPresent(Category.self, forKey: .selectedCategory)
let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)
self.recipePath = recipePathIds.compactMap { DataModel.shared[$0] } // Ignorer les éléments supprimés
}
}
Stockez les IDs (pas les objets complets du modèle) et utilisez compactMap pour gérer gracieusement les éléments supprimés. Ajoutez une propriété calculée jsonData et objectWillChangeSequence pour l'intégration avec SceneStorage comme indiqué en 4.1.
Intégration des Onglets + Navigation
5.1 Syntaxe des onglets (iOS 18+) (WWDC 2024, 4:27)
TabView {
Tab("Regarder maintenant", systemImage: "play") {
WatchNowView()
}
Tab("Bibliothèque", systemImage: "books.vertical") {
LibraryView()
}
Tab("Recherche", systemImage: "magnifyingglass") {
SearchView()
}
}
5.2 Intégration Pile d'Onglets + Navigation (iOS 18+)
TabView {
Tab("Accueil", systemImage: "house") {
NavigationStack {
HomeView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
}
Tab("Paramètres", systemImage: "gear") {
NavigationStack {
SettingsView()
}
}
}
Chaque onglet maintient son propre NavigationStack, préservant la pile de navigation lors du changement d'onglet.
5.3 iOS 26+ Liquid Glass Navigation (WWDC 2025, 312)
// La navigation Liquid Glass s'applique automatiquement aux barres de navigation et barres d'onglets
TabView {
Tab("Accueil", systemImage: "house") {
NavigationStack {
HomeView()
}
}
Tab("Recherche", systemImage: "magnifyingglass") {
NavigationStack {
SearchView()
}
}
}
.tabViewStyle(.tabBar) // La barre d'onglets obtient un aspect Liquid Glass
// Barre d'onglets flottante (iOS 26+)
.tabBarFloating()
// Recherche alignée en bas (iOS 26+)
.searchPresentationToolbarBehavior(.bottomAligned)
Patron Coordinateur (Alternative UIKit)
6.1 Quand utiliser un coordinateur UIKit
Envisagez de passer à UINavigationController avec un pattern coordinateur Swift lorsque :
- Vous avez besoin de transitions personnalisées complexes non prises en charge par SwiftUI
- Vous construisez des architectures d'intégration (mélange de vues UIKit et SwiftUI)
- Vous héritez d'un code base UIKit avec des coordinateurs existants
6.2 Exemple de coordinateur Swift
class AppCoordinator: NSObject {
let navigationController: UINavigationController
init(navigationController: UINavigationController) {
self.navigationController = navigationController
}
func start() {
let rootVC = CategoriesViewController()
rootVC.coordinator = self
navigationController.pushViewController(rootVC, animated: false)
}
func showRecipes(for category: Category) {
let recipesVC = RecipesViewController(category: category)
recipesVC.coordinator = self
navigationController.pushViewController(recipesVC, animated: true)
}
func showRecipeDetail(_ recipe: Recipe) {
let detailVC = RecipeDetailViewController(recipe: recipe)
navigationController.pushViewController(detailVC, animated: true)
}
}
Pièges Courants
Problème : navigationDestination placé à l'intérieur d'un conteneur paresseux
// Incorrect : Peut ne pas être chargé
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(value: item) {
ItemRow(item: item)
}
.navigationDestination(for: Item.self) { item in // Ne faites pas cela
ItemDetailView(item: item)
}
}
}
}
Solution : Déplacez navigationDestination(for:) en dehors du conteneur paresseux.
Problème : Oubli de lier NavigationStack(path: $path)
// Incorrect : Le lien appuyé n'ajoute pas au path
NavigationStack {
List {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
Solution : Utilisez NavigationStack(path: $path) et gérez le path (par exemple, path.append(item)) si vous avez besoin d'un contrôle programmatique.
Problème : Type non Codable pour NavigationPath
struct MyModel: Hashable { // Oublier 'Codable'
let id: UUID
let name: String
}
@State private var path = NavigationPath() // Ne peut pas encoder/décoder MyModel
Solution : Conformez les types à Codable pour la restauration d'état.
Thèmes Connexes
- Anti-patrons et arbres de décision :
axiom-swiftui-nav - Dépannage des problèmes :
axiom-swiftui-nav-diag - Documentation Apple : NavigationStack, NavigationSplitView, NavigationPath
- Vidéos WWDC : The SwiftUI navigation cookbook (2022), Meet SwiftUI navigation (2022), What's new in SwiftUI (2024), What's new in SwiftUI (2025)