NavigationStack: czym jest, stos nawigacyjny w SwiftUI

Czym jest NavigationStack w SwiftUI?

NavigationStack to kontenerowe View implementujące nawigację opartą na stosie (LIFO). Zarządza historią przejść, pozwalając umieszczać nowe ekrany na stosie i wracać za pomocą systemowego przycisku «Wstecz» lub programowo. NavigationStack jest częścią SwiftUI od iOS 16, iPadOS 16, macOS 13, watchOS 9 i tvOS 16.

Główną nowością NavigationStack jest typowo bezpieczna ścieżka nawigacji. Zamiast bezpośredniego wskazywania destination podczas tworzenia NavigationLink, umieszczasz w ścieżce wartość (value), a rejestracja docelowego View odbywa się osobno przez modyfikator .navigationDestination(for:destination:). To rozdziela nawigację i wyświetlanie, czyniąc kod bardziej modułowym i testowalnym.

Według WWDC 2022 (Session 10054), NavigationStack używa nowego mechanizmu nawigacji opartego na ObservableObject i cyklu życia SwiftUI. W przeciwieństwie do NavigationView, który opierał się na UINavigationController pod maską, NavigationStack jest w pełni zaimplementowany w SwiftUI, co poprawia przewidywalność i kompatybilność z cyklem życia SwiftUI.

Podstawowa struktura NavigationStack

NavigationStack przyjmuje główne View i opcjonalną ścieżkę nawigacji (Binding do NavigationPath lub tablicy wartości Hashable). Wszystkie podrzędne ekrany są umieszczane w stosie przez NavigationLink lub programowe dodawanie wartości do ścieżki.

NavigationStack vs NavigationView: porównanie

NavigationView był głównym kontenerem nawigacyjnym SwiftUI do iOS 16. Automatycznie zarządzał UINavigationController pod maską, co prowadziło do szeregu problemów: nieprzewidywalne zachowanie przy zmianie danych, trudności z programową nawigacją i brak typowego bezpieczeństwa.

Kluczowa zaleta NavigationStack — typowo bezpieczna nawigacja. Definiujesz ścieżkę jako tablicę konkretnych typów (lub NavigationPath dla heterogenicznych stosów) i rejestrujesz destination dla każdego typu. To eliminuje błędy niezgodności typów i czyni nawigację przewidywalną.

NavigationView jest przestarzały w iOS 17. Apple zaleca migrację na NavigationStack dla wszystkich nowych projektów oraz przy aktualizacji minimalnej wersji do iOS 16.

NavigationPath: typowo bezpieczne zarządzanie stosem

NavigationPath to typ reprezentujący ścieżkę nawigacji w NavigationStack. Może przechowywać wartości heterogeniczne (AnyHashable) lub być używany z konkretnym typem przez Binding do tablicy [T: Hashable]. NavigationPath automatycznie się koduje i dekoduje w celu zachowania stanu.

struct ContentView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: String.self) { value in
                    DetailView(id: value)
                }
                .navigationDestination(for: Int.self) { value in
                    NumberView(number: value)
                }
        }
    }

    func goToRoot() {
        path.removeLast(path.count)
    }

    func pushDeepLink() {
        path.append("detail_42")
    }
}

Stos heterogeniczny: NavigationPath może zawierać wartości różnych typów, jeśli implementują Hashable. Na przykład pierwszy ekran może przyjmować String (ID), drugi — Int (numer), trzeci — niestandardowy enum Route. Do wyświetlenia każdego typu rejestruje się osobny .navigationDestination.

Obsługa Codable: NavigationPath implementuje Codable, jeśli wszystkie wartości w ścieżce są również Codable + Hashable. Pozwala to zapisywać i przywracać stan nawigacji przy ponownym uruchomieniu aplikacji lub przejściu do trybu tła.

NavigationDestination: rejestracja docelowych ekranów

.navigationDestination(for:destination:) — modyfikator rejestrujący docelowe View dla konkretnego typu danych. Gdy NavigationLink umieszcza w ścieżce wartość tego typu, SwiftUI automatycznie znajduje odpowiedni .navigationDestination i tworzy ekran.

enum AppRoute: Hashable {
    case profile(UserID)
    case settings
    case about
}

struct AppNavigation: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: AppRoute.self) { route in
                    switch route {
                    case .profile(let id):
                        ProfileView(userId: id)
                    case .settings:
                        SettingsView()
                    case .about:
                        AboutView()
                    }
                }
        }
    }
}

// Navigate: path.append(AppRoute.profile("user_123"))

Ważna zasada: .navigationDestination musi być zastosowany do View, które znajduje się wewnątrz NavigationStack, i zanim NavigationLink umieści wartość w ścieżce. Zwykle dodaje się go do głównego View lub do kontenera sekcji. Jeśli .navigationDestination nie zostanie znaleziony dla typu wartości, przejście nie nastąpi.

Według SwiftUI Engineering (2023), .navigationDestination może być zarejestrowany na różnych poziomach hierarchii. SwiftUI szuka najbliższego pasującego destination przy próbie nawigacji. Pozwala to nadpisywać destination dla jednego typu w różnych częściach aplikacji.

Wzorce użycia NavigationStack

Wzorzec 1: nawigacja przez enum Route. Zdefiniuj enum z wartościami powiązanymi dla wszystkich ekranów aplikacji. Użyj jednego .navigationDestination dla AppRoute i switch do routingu. Zapewnia to jeden źródło prawdy dla wszystkich możliwych przejść w aplikacji.

struct StoreView: View {
    @State private var path: [ProductRoute] = []

    var body: some View {
        NavigationStack(path: $path) {
            ProductGrid()
                .navigationDestination(for: ProductRoute.self) { route in
                    switch route {
                    case .detail(let product):
                        ProductDetail(product: product)
                    case .reviews(let productId):
                        ReviewsView(productId: productId)
                    }
                }
        }
    }
}

enum ProductRoute: Hashable {
    case detail(Product)
    case reviews(String)
}

Wzorzec 2: programowa nawigacja i deep linking. NavigationStack pozwala programowo zarządzać stosem: dodawać, usuwać ekrany i wracać do korzenia. Jest to niezbędne dla powiadomień push, linków głębokich i przywracania nawigacji po ponownym uruchomieniu.

Wzorzec 3: tablica typów zamiast NavigationPath. Jeśli wszystkie ekrany używają jednego typu (np. String lub niestandardowy enum), użyj Binding do [T]. Daje to bardziej rygorystyczną typizację i lepszą wydajność niż NavigationPath. NavigationPath jest uzasadniony dla heterogenicznych stosów z różnymi typami ekranów.

Według Point-Free (2024), NavigationStack z enum Route to preferowany sposób organizacji nawigacji w aplikacjach SwiftUI. Czyni wszystkie możliwe przejścia jawnymi, typowo bezpiecznymi i testowalnymi, co jest szczególnie ważne dla dużych projektów z dziesiątkami ekranów.