Referencia de la API de Navegación de SwiftUI
Resumen
Las APIs de navegación de SwiftUI proporcionan una navegación programática basada en datos que escala desde pilas simples hasta diseños complejos de varias columnas. Introducidas en iOS 16 (2022) con NavigationStack y NavigationSplitView, evolucionaron en iOS 18 (2024) con la unificación de pestañas/barra lateral y se refinaron en iOS 26 (2025) con el diseño Liquid Glass.
Cronología de evolución
- 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basado en valores
- 2024 (iOS 18) Unificación de pestañas/barra lateral, estilo
sidebarAdaptable, transición de navegación con zoom - 2025 (iOS 26) Navegación Liquid Glass, búsqueda alineada en la parte inferior, barras de pestañas flotantes,
backgroundExtensionEffect
Capacidades clave
- Navegación basada en datos
NavigationPathrepresenta el estado de la pila, lo que permite push/pop programático y enlaces profundos - Diseños de varias columnas
NavigationSplitViewse adapta automáticamente (3 columnas en iPad → pila única en iPhone) - Restauración de estado
NavigationPathcodificable +SceneStoragepara persistencia entre lanzamientos de la aplicación - Integración de pestañas
NavigationStackpor pestaña con preservación del estado al cambiar de pestaña (iOS 18+) - Liquid Glass Barras de navegación, barras laterales y barras de herramientas de vidrio automáticas (iOS 26+)
Cuándo usar vs UIKit
- Navegación SwiftUI Nuevas aplicaciones, multiplataforma, flujos de navegación más simples → Usar NavigationStack/SplitView
- UINavigationController Patrones de coordinador complejos, código heredado, características específicas de UIKit → Considerar UIKit
Habilidades relacionadas
- Usar
axiom-swiftui-navpara anti-patrones, árboles de decisión, escenarios de presión - Usar
axiom-swiftui-nav-diagpara solución sistemática de problemas de navegación
Cuándo Usar Esta Habilidad
Usa esta habilidad cuando:
- Implementes APIs de navegación NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
- Realices enlaces profundos o restauración de estado Enrutamiento de URL, NavigationPath codificable, SceneStorage
- Adoptes características de iOS 26+ Navegación Liquid Glass, búsqueda alineada en la parte inferior, minimización de la barra de pestañas
- Elijas una arquitectura de navegación Pila vs SplitView vs patrones de coordinador
Evolución de la API
Cronología
| Año | Versión de iOS | Características clave |
|---|---|---|
| 2020 | iOS 14 | NavigationView (obsoleto desde iOS 16) |
| 2022 | iOS 16 | NavigationStack, NavigationSplitView, NavigationPath, NavigationLink basado en valores |
| 2024 | iOS 18 | Unificación de pestañas/barra lateral, sidebarAdaptable, TabSection, transiciones con zoom |
| 2025 | iOS 26 | Navegación Liquid Glass, backgroundExtensionEffect, tabBarMinimizeBehavior |
NavigationView (Obsoleto)
NavigationView está obsoleto desde iOS 16. Usa NavigationStack (push/pop de una columna) o NavigationSplitView (varias columnas) exclusivamente en código nuevo. Mejoras clave: un solo NavigationPath reemplaza los enlaces isActive por enlace, seguridad de tipos basada en valores, restauración de estado codificable incorporada. Consulta la documentación "Migración a nuevos tipos de navegación".
Referencia Completa de NavigationStack
NavigationStack representa una interfaz de push-pop como Ajustes en iPhone o Preferencias del Sistema en macOS.
1.1 Creación de NavigationStack
NavigationStack Básico
NavigationStack {
List(Category.allCases) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Categories")
.navigationDestination(for: Category.self) { category in
CategoryDetail(category: category)
}
}
Con Enlace de Ruta (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)
}
}
El enlace de ruta + NavigationLink que presenta valores + navigationDestination(for:) forman el patrón central de navegación basada en datos.
1.2 NavigationLink (Basado en Valores)
NavigationLink que Presenta Valores
// Correcto: Basado en valores (iOS 16+)
NavigationLink(recipe.name, value: recipe)
// Correcto: Con etiqueta personalizada
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
// Obsoleto: Basado en vista (iOS 13-15)
NavigationLink(recipe.name) {
RecipeDetail(recipe: recipe) // No usar en código nuevo
}
Cómo funciona NavigationLink con NavigationStack
- NavigationStack mantiene una colección
path - Tocar un enlace que presenta un valor agrega el valor a la ruta
- NavigationStack asigna modificadores
navigationDestinationsobre los valores de la ruta - Las vistas se colocan en la pila según las asignaciones de destino
1.3 Modificador navigationDestination
Tipo Único
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
Múltiples Tipos
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-patrones de Navegación
- Nunca mezcles
navigationDestination(for:)yNavigationLink(destination:)en la misma jerarquía de NavigationStack — causa comportamiento indefinido - Registra
navigationDestination(for:)una vez por tipo de datos — los duplicados hacen que aparezca la vista incorrecta
Reglas de ubicación
- Coloca
navigationDestinationfuera de los contenedores perezosos (no dentro de ForEach) - Colócalo cerca de los NavigationLinks relacionados para organizar el código
- Debe estar dentro de la jerarquía de NavigationStack
// Correcto: Fuera del contenedor perezoso
ScrollView {
LazyVGrid(columns: columns) {
ForEach(recipes) { recipe in
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
}
}
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
// Incorrecto: Dentro de ForEach (puede que no se cargue)
ForEach(recipes) { recipe in
NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
.navigationDestination(for: Recipe.self) { r in // No hagas esto
RecipeDetail(recipe: r)
}
}
1.4 NavigationPath
NavigationPath es una colección de tipo borrado para pilas de navegación heterogéneas.
Array Tipado vs NavigationPath
// Array tipado: Todos los valores del mismo tipo
@State private var path: [Recipe] = []
// NavigationPath: Tipos mixtos
@State private var path = NavigationPath()
Operaciones de NavigationPath
// Agregar valor
path.append(recipe)
// Volver al anterior
path.removeLast()
// Volver a la raíz
path.removeLast(path.count)
// o
path = NavigationPath()
// Verificar conteo
if path.count > 0 { ... }
// Enlace profundo: Establecer múltiples valores
path.append(category)
path.append(recipe)
Soporte Codable
// NavigationPath es Codable cuando todos los valores son Codable
@State private var path = NavigationPath()
// Codificar
let data = try JSONEncoder().encode(path.codable)
// Decodificar
let codableRep = try JSONDecoder().decode(NavigationPath.CodableRepresentation.self, from: data)
path = NavigationPath(codableRep)
Referencia Completa de NavigationSplitView
NavigationSplitView crea diseños de varias columnas que se adaptan al tamaño del dispositivo.
2.1 Diseño de Dos Columnas
Básico de Dos Columnas (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 Diseño de Tres Columnas
Agrega un cierre content: entre la barra lateral y el detalle para una columna intermedia:
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 con NavigationStack
Coloca un NavigationStack(path:) dentro de la columna de detalle para una exploración en profundidad de cuadrícula a detalle mientras se preserva la selección de la barra lateral:
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { ... }
} detail: {
NavigationStack(path: $path) {
RecipeGrid(category: selectedCategory)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
2.4 Visibilidad de Columna
@State private var columnVisibility: NavigationSplitViewVisibility = .all
NavigationSplitView(columnVisibility: $columnVisibility) {
Sidebar()
} content: {
Content()
} detail: {
Detail()
}
// Controlar visibilidad programáticamente
columnVisibility = .detailOnly // Ocultar barra lateral y contenido
columnVisibility = .all // Mostrar todas las columnas
columnVisibility = .automatic // El sistema decide
2.5 Adaptación Automática
NavigationSplitView se adapta automáticamente:
- iPad horizontal Todas las columnas visibles (según la configuración)
- iPad vertical/Slide Over Se colapsa a superposición o una sola columna
- iPhone Pila de navegación única
- Apple Watch/TV Pila de navegación única
Los cambios de selección se traducen automáticamente a push/pop en iPhone.
2.6 Barra Lateral Liquid Glass de iOS 26+ (WWDC 2025, 323)
NavigationSplitView {
List { ... }
} detail: {
DetailView()
}
// La barra lateral obtiene automáticamente la apariencia Liquid Glass en iPad/macOS
// Extiende el contenido detrás de la barra lateral de vidrio
.backgroundExtensionEffect() // Refleja y difumina el contenido fuera del área segura
Enlaces Profundos y Enrutamiento de URL
3.1 Patrón de Enlace Profundo
Usa .onOpenURL para recibir URLs, analízalas con URLComponents, luego manipula NavigationPath:
.onOpenURL { url in
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let host = components.host else { return }
path.removeLast(path.count) // Primero volver a la raíz
// Analizar host/ruta para determinar el destino, luego path.append(valor)
}
Para enlaces profundos de varios pasos (myapp://category/desserts/recipe/apple-pie), itera sobre los componentes de la ruta de la URL y agrega cada valor resuelto para construir la pila de navegación completa.
Para ejemplos completos de enlaces profundos, diagnóstico de errores y flujos de trabajo de prueba, consulta axiom-swiftui-nav-diag (Patrón 3).
Restauración de Estado
4.1 Restauración Completa de Estado (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 {
// Restaurar al aparecer
if let data = data {
navModel.jsonData = data
}
// Guardar en cambios
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
.environmentObject(dataModel)
}
}
4.2 NavigationModel Codificable
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds // Almacenar IDs, no objetos completos
}
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] } // Descartar elementos eliminados
}
}
Almacena IDs (no objetos de modelo completos) y usa compactMap para manejar elementos eliminados de forma segura. Agrega la propiedad computada jsonData y objectWillChangeSequence para la integración con SceneStorage como se muestra en 4.1.
Integración de Pestañas + Navegación
5.1 Sintaxis de Pestañas (iOS 18+) (WWDC 2024, 4:27)
TabView {
Tab("Watch Now", systemImage: "play") {
WatchNowView()
}
Tab("Library", systemImage: "books.vertical") {
LibraryView()
}
...
}