Communitygithub.com

ComeOnOliver/skillshub

Référence — Guide complet de navigation SwiftUI couvrant NavigationStack (iOS 16+), NavigationSplitView (iOS 16+), NavigationPath, deep linking, restauration d'état, intégration Tab+Navigation (iOS 18+), navigation Liquid Glass (iOS 26+) et patterns de coordinateur

Qu'est-ce que skillshub ?

Cette compétence constitue une référence exhaustive pour la mise en œuvre de la navigation en SwiftUI, depuis les bases jusqu'aux fonctionnalités les plus avancées. Elle couvre les API introduites avec iOS 16 (NavigationStack, NavigationSplitView, NavigationPath), leur évolution avec iOS 18 (unification Tab/Sidebar, sidebarAdaptable) et les dernières innovations d'iOS 26 (Liquid Glass). Utile pour les développeurs créant des applications multi-plateformes ou complexes, elle fournit des exemples concrets, des règles de placement pour les modificateurs comme `navigationDestination`, et des patterns pour le deep linking et la restauration d'état via `SceneStorage`. La compétence explique comment combiner des vues à onglets avec des piles de navigation par onglet (iOS 18+), et comment utiliser NavigationPath pour des piles hétérogènes avec support Codable. Elle s'applique à tous les frameworks Apple utilisant SwiftUI (iOS, iPadOS, macOS, watchOS, tvOS).

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-nav-ref

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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-nav pour les anti-patrons, les arbres de décision, les scénarios de pression
  • Utilisez axiom-swiftui-nav-diag pour 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éeVersion iOSFonctionnalités clés
2020iOS 14NavigationView (dépréciée iOS 16)
2022iOS 16NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basé sur une valeur
2024iOS 18Unification Tab/Sidebar, sidebarAdaptable, TabSection, transitions de zoom
2025iOS 26Navigation 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

  1. NavigationStack maintient une collection path
  2. Appuyer sur un lien présentant une valeur ajoute la valeur au path
  3. NavigationStack applique les modificateurs navigationDestination sur les valeurs du chemin
  4. 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:) et NavigationLink(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 navigationDestination en 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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

Skills associés