SwiftUI Navigations-API-Referenz
Überblick
Die Navigations-APIs von SwiftUI bieten datengesteuerte, programmatische Navigation, die von einfachen Stacks bis zu komplexen Multi-Column-Layouts skaliert. Eingeführt in iOS 16 (2022) mit NavigationStack und NavigationSplitView, weiterentwickelt in iOS 18 (2024) mit Tab-/Sidebar-Vereinheitlichung und verfeinert in iOS 26 (2025) mit Liquid Glass Design.
Entwicklungs-Zeitleiste
- 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, wertbasierter NavigationLink
- 2024 (iOS 18) Tab-/Sidebar-Vereinheitlichung, sidebarAdaptable-Stil, Zoom-Navigationsübergang
- 2025 (iOS 26) Liquid Glass Navigations-Chrome, unten ausgerichtete Suche, schwebende Tab-Leisten, backgroundExtensionEffect
Hauptfunktionen
- Datengesteuerte Navigation NavigationPath repräsentiert den Stack-Status und ermöglicht programmatisches Push/Pop und Deep Linking
- Multi-Column-Layouts NavigationSplitView passt sich automatisch an (3-Spalten auf iPad → einzelner Stack auf iPhone)
- Zustandswiederherstellung Codable NavigationPath + SceneStorage für Persistenz über App-Starts hinweg
- Tab-Integration Pro-Tab NavigationStack mit Zustandserhaltung beim Tab-Wechsel (iOS 18+)
- Liquid Glass Automatische Glas-Navigationsleisten, Sidebars und Toolbars (iOS 26+)
Wann verwenden vs. UIKit
- SwiftUI-Navigation Neue Apps, plattformübergreifend, einfachere Navigationsflüsse → NavigationStack/SplitView verwenden
- UINavigationController Komplexe Koordinatormuster, Legacy-Code, spezifische UIKit-Funktionen → UIKit in Betracht ziehen
Verwandte Skills
- Verwenden Sie
axiom-swiftui-navfür Anti-Patterns, Entscheidungsbäume, Druckszenarien - Verwenden Sie
axiom-swiftui-nav-diagfür systematische Fehlerbehebung von Navigationsproblemen
Wann dieses Skill verwenden
Verwenden Sie dieses Skill, wenn:
- Implementierung von Navigations-APIs NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
- Deep Linking oder Zustandswiederherstellung URL-Routing, Codable NavigationPath, SceneStorage
- Übernahme von iOS 26+-Funktionen Liquid Glass Navigation, unten ausgerichtete Suche, Minimierung der Tab-Leiste
- Wahl der Navigationsarchitektur Stack vs. SplitView vs. Koordinatormuster
API-Entwicklung
Zeitleiste
| Jahr | iOS-Version | Hauptfunktionen |
|---|---|---|
| 2020 | iOS 14 | NavigationView (veraltet ab iOS 16) |
| 2022 | iOS 16 | NavigationStack, NavigationSplitView, NavigationPath, wertbasierter NavigationLink |
| 2024 | iOS 18 | Tab-/Sidebar-Vereinheitlichung, sidebarAdaptable, TabSection, Zoom-Übergänge |
| 2025 | iOS 26 | Liquid Glass Navigation, backgroundExtensionEffect, tabBarMinimizeBehavior |
NavigationView (Veraltet)
NavigationView ist ab iOS 16 veraltet. Verwenden Sie ausschließlich NavigationStack (Einzelspalten Push/Pop) oder NavigationSplitView (Mehrspalten) in neuem Code. Wichtige Verbesserungen: Ein einzelner NavigationPath ersetzt die per-Link isActive-Bindungen, wertbasierte Typsicherheit, integrierte Codable-Zustandswiederherstellung. Siehe Dokumentation „Migration zu neuen Navigationstypen“.
NavigationStack vollständige Referenz
NavigationStack repräsentiert eine Push-Pop-Oberfläche wie Einstellungen auf dem iPhone oder Systemeinstellungen auf dem Mac.
1.1 NavigationStack erstellen
Basis NavigationStack
NavigationStack {
List(Category.allCases) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Categories")
.navigationDestination(for: Category.self) { category in
CategoryDetail(category: category)
}
}
Mit Pfadbindung (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("Categories")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.environmentObject(dataModel)
}
}
Pfadbindung + wertpräsentierender NavigationLink + navigationDestination(for:) bilden das zentrale datengesteuerte Navigationsmuster.
1.2 NavigationLink (Wertbasiert)
Wertpräsentierender NavigationLink
// Richtig: Wertbasiert (iOS 16+)
NavigationLink(recipe.name, value: recipe)
// Richtig: Mit benutzerdefiniertem Label
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
// Veraltet: Ansichtsbasiert (iOS 13-15)
NavigationLink(recipe.name) {
RecipeDetail(recipe: recipe) // Nicht in neuem Code verwenden
}
Wie NavigationLink mit NavigationStack funktioniert
- NavigationStack verwaltet eine
path-Sammlung - Tippen auf einen wertpräsentierenden Link fügt den Wert an die Sammlung an
- NavigationStack wendet
navigationDestination-Modifikatoren auf die Pfadwerte an - Ansichten werden basierend auf den Zielzuordnungen auf den Stack geschoben
1.3 navigationDestination-Modifikator
Einzelner Typ
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
Mehrere Typen
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)
}
}
Navigations-Anti-Patterns
- Mischen Sie niemals
navigationDestination(for:)undNavigationLink(destination:)in derselben NavigationStack-Hierarchie – verursacht undefiniertes Verhalten - Registrieren Sie
navigationDestination(for:)einmal pro Datentyp – Duplikate führen dazu, dass die falsche Ansicht erscheint
Platzierungsregeln
- Platzieren Sie
navigationDestinationaußerhalb von Lazy-Containern (nicht innerhalb von ForEach) - Platzieren Sie es in der Nähe verwandter NavigationLinks zur Code-Organisation
- Muss innerhalb der NavigationStack-Hierarchie sein
// Richtig: Außerhalb des Lazy-Containers
ScrollView {
LazyVGrid(columns: columns) {
ForEach(recipes) { recipe in
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
}
}
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
// Falsch: Innerhalb von ForEach (wird möglicherweise nicht geladen)
ForEach(recipes) { recipe in
NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
.navigationDestination(for: Recipe.self) { r in // Nicht so machen
RecipeDetail(recipe: r)
}
}
1.4 NavigationPath
NavigationPath ist eine typgelöschte Sammlung für heterogene Navigationsstapel.
Typisiertes Array vs. NavigationPath
// Typisiertes Array: Alle Werte gleicher Typ
@State private var path: [Recipe] = []
// NavigationPath: Gemischte Typen
@State private var path = NavigationPath()
NavigationPath-Operationen
// Wert anhängen
path.append(recipe)
// Zum vorherigen zurück
path.removeLast()
// Zur Wurzel zurück
path.removeLast(path.count)
// oder
path = NavigationPath()
// Anzahl prüfen
if path.count > 0 { ... }
// Deep Link: Mehrere Werte setzen
path.append(category)
path.append(recipe)
Codable-Unterstützung
// NavigationPath ist Codable, wenn alle Werte Codable sind
@State private var path = NavigationPath()
// Codieren
let data = try JSONEncoder().encode(path.codable)
// Decodieren
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)
NavigationSplitView vollständige Referenz
NavigationSplitView erstellt Multi-Column-Layouts, die sich an die Gerätegröße anpassen.
2.1 Zwei-Spalten-Layout
Basis Zwei-Spalten (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("Categories")
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Select a recipe")
}
}
}
}
2.2 Drei-Spalten-Layout
Fügen Sie einen content:-Closure zwischen Sidebar und Detail für eine mittlere Spalte hinzu:
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 mit NavigationStack
Platzieren Sie einen NavigationStack(path:) innerhalb der Detailspalte für Grid-zu-Detail-Drill-Down, während die Sidebar-Auswahl erhalten bleibt:
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
NavigationStack(path: $path) {
RecipeGrid(category: selectedCategory)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
2.4 Spaltensichtbarkeit
@State private var columnVisibility: NavigationSplitViewVisibility = .all
NavigationSplitView(columnVisibility: $columnVisibility) {
Sidebar()
} content: {
Content()
} detail: {
Detail()
}
// Programmatisch Sichtbarkeit steuern
columnVisibility = .detailOnly // Sidebar und Inhalt ausblenden
columnVisibility = .all // Alle Spalten anzeigen
columnVisibility = .automatic // System entscheidet
2.5 Automatische Anpassung
NavigationSplitView passt sich automatisch an:
- iPad Landscape Alle Spalten sichtbar (je nach Konfiguration)
- iPad Portrait/Slide Over Kollabiert zu Overlay oder einzelner Spalte
- iPhone Einzelner Navigationsstapel
- Apple Watch/TV Einzelner Navigationsstapel
Auswahländerungen werden automatisch in Push/Pop auf dem iPhone übersetzt.
2.6 iOS 26+ Liquid Glass Sidebar (WWDC 2025, 323)
NavigationSplitView {
List { ... }
} detail: {
DetailView()
}
// Sidebar erhält automatisch Liquid Glass-Erscheinungsbild auf iPad/macOS
// Inhalt hinter Glas-Sidebar erweitern
.backgroundExtensionEffect() // Spiegelt und weicht Inhalt außerhalb des Safe Area
Deep Linking und URL-Routing
3.1 Deep Link-Muster
Verwenden Sie .onOpenURL, um URLs zu empfangen, parsen Sie sie mit URLComponents und manipulieren Sie dann den NavigationPath:
.onOpenURL { url in
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let host = components.host else { return }
path.removeLast(path.count) // Zuerst zur Wurzel zurück
// Host/Pfad parsen, um Ziel zu bestimmen, dann path.append(value)
}
Für mehrstufige Deep Links (myapp://category/desserts/recipe/apple-pie) iterieren Sie über die URL-Pfadkomponenten und hängen jeden aufgelösten Wert an, um den vollständigen Navigationsstapel aufzubauen.
Für umfassende Deep-Linking-Beispiele, Fehlerdiagnose und Test-Workflows siehe axiom-swiftui-nav-diag (Muster 3).
Zustandswiederherstellung
4.1 Vollständige Zustandswiederherstellung (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("Categories")
} detail: {
NavigationStack(path: $navModel.recipePath) {
RecipeGrid(category: navModel.selectedCategory)
}
}
.task {
// Beim Erscheinen wiederherstellen
if let data = data {
navModel.jsonData = data
}
// Bei Änderungen speichern
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
.environmentObject(dataModel)
}
}
4.2 Codable NavigationModel
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds // Speichere IDs, nicht vollständige Objekte
}
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] } // Gelöschte Elemente verwerfen
}
}
Speichern Sie IDs (nicht vollständige Modellobjekte) und verwenden Sie compactMap, um gelöschte Elemente elegant zu behandeln. Fügen Sie die jsonData-berechnete Eigenschaft und objectWillChangeSequence für die SceneStorage-Integration hinzu, wie in 4.1 gezeigt.
Tab + Navigationsintegration
5.1 Tab-Syntax (iOS 18+) (WWDC 2024, 4:27)
TabView {
Tab("Watch Now", systemImage: "play") {
WatchNowView()
}
Tab("Library", systemImage: "books.vertical") {
LibraryView()
}
...
}