Navegación en SwiftUI
Cuándo Usar Esta Habilidad
Úsala cuando:
- Elijas la arquitectura de navegación (NavigationStack vs NavigationSplitView vs TabView)
- Implementes navegación programática con NavigationPath
- Configures enlaces profundos y enrutamiento de URL
- Implementes restauración de estado para la navegación
- Adoptes patrones de pestañas/barra lateral (iOS 18+)
- Implementes patrones de coordinador/enrutador
- Solicites revisión de código de una implementación de navegación antes del lanzamiento
Habilidades Relacionadas
- Usa
axiom-swiftui-nav-diagpara solución sistemática de problemas de navegación - Usa
axiom-swiftui-nav-refpara referencia completa de API (incluyendo personalización de pestañas, funciones de iOS 26+) con todos los ejemplos de WWDC
Ejemplos de Prompts
Estas son preguntas reales que los desarrolladores hacen y que esta habilidad está diseñada para responder:
1. "¿Debería usar NavigationStack o NavigationSplitView para mi aplicación?"
-> La habilidad proporciona un árbol de decisión basado en los dispositivos objetivo, la profundidad de la jerarquía de contenido y los requisitos multiplataforma
2. "¿Cómo navego programáticamente en SwiftUI?"
-> La habilidad muestra patrones de manipulación de NavigationPath para push, pop, pop-to-root y enlaces profundos
3. "Mis enlaces profundos no funcionan. La aplicación se abre pero muestra la pantalla incorrecta."
-> La habilidad cubre patrones de análisis de URL, orden de construcción de rutas y problemas de temporización con onOpenURL
4. "El estado de navegación se pierde cuando mi aplicación pasa a segundo plano."
-> La habilidad demuestra NavigationPath codificable, persistencia con SceneStorage y restauración resistente a fallos
5. "¿Cómo implemento un patrón de coordinador en SwiftUI?"
-> La habilidad proporciona ejemplos del patrón Router junto con orientación sobre cuándo los coordinadores añaden valor versus complejidad
Banderas Rojas — Anti-patrones a Prevenir
Si estás haciendo CUALQUIERA de estos, DETENTE y usa los patrones de esta habilidad:
❌ CRÍTICO — Nunca Hagas Esto
1. Usar NavigationView obsoleto en iOS 16+
// ❌ INCORRECTO — Obsoleto, comportamiento diferente en iOS 16+
NavigationView {
List { ... }
}
.navigationViewStyle(.stack)
Por qué falla: NavigationView está obsoleto desde iOS 16. Carece de soporte para NavigationPath, lo que hace que la navegación programática y los enlaces profundos no sean fiables. El comportamiento diferente entre versiones de iOS causa errores.
2. Usar NavigationLink basado en vistas para navegación programática
// ❌ INCORRECTO — No se puede controlar programáticamente
NavigationLink("Receta") {
RecipeDetail(recipe: recipe) // Destino de vista, sin valor
}
Por qué falla: Los enlaces basados en vistas no se pueden controlar programáticamente. No hay manera de hacer un enlace profundo o volver a este destino. Obsoleto desde iOS 16.
3. Poner navigationDestination dentro de contenedores perezosos
// ❌ INCORRECTO — Puede no cargarse cuando se necesita
LazyVGrid(columns: columns) {
ForEach(items) { item in
NavigationLink(value: item) { ... }
.navigationDestination(for: Item.self) { item in // No hagas esto
ItemDetail(item: item)
}
}
}
Por qué falla: Los contenedores perezosos no cargan todas las vistas inmediatamente. Es posible que navigationDestination no sea visible para NavigationStack, causando que la navegación falle silenciosamente.
4. Almacenar objetos completos del modelo en NavigationPath para restauración
// ❌ INCORRECTO — Duplica datos, obsoleto al restaurar
class NavigationModel: Codable {
var path: [Recipe] = [] // Objetos Recipe completos
}
Por qué falla: Duplica datos que ya están en tu modelo. Al restaurar, los datos de Recipe pueden estar obsoletos (editados/eliminados en otro lugar). Usa IDs y resuelve a datos actuales.
5. Modificar NavigationPath fuera de MainActor
// ❌ INCORRECTO — Actualización de UI fuera del hilo principal
Task.detached {
await viewModel.path.append(recipe) // Hilo de fondo
}
Por qué falla: NavigationPath está vinculado a la UI. Las modificaciones deben ocurrir en MainActor o el estado de navegación se corrompe. Puede causar fallos o fallos silenciosos.
6. Falta de aislamiento @MainActor para el estado de navegación
// ❌ INCORRECTO — No aislado en MainActor
class Router: ObservableObject {
@Published var path = NavigationPath() // Sin @MainActor
}
Por qué falla: En concurrencia estricta de Swift 6, las propiedades @Published accedidas desde vistas SwiftUI requieren aislamiento de MainActor. Causa advertencias de condición de carrera y posibles fallos.
7. No manejar el estado de navegación en aplicaciones con múltiples pestañas
// ❌ INCORRECTO — NavigationPath compartido entre pestañas
TabView {
Tab("Inicio") { HomeView() }
Tab("Ajustes") { SettingsView() }
}
// Todas las pestañas comparten el mismo NavigationStack — ¡incorrecto!
Por qué falla: Cada pestaña debe tener su propio NavigationStack para preservar el estado de navegación al cambiar de pestaña. El estado compartido causa una UX confusa.
8. Ignorar errores de decodificación de NavigationPath
// ❌ INCORRECTO — Fallo por datos inválidos
let path = NavigationPath(try! decoder.decode(NavigationPath.CodableRepresentation.self, from: data))
Por qué falla: El usuario puede haber eliminado elementos que estaban en la ruta. El esquema puede haber cambiado. Forzar el desenvolvimiento causa un fallo al restaurar.
Pasos Iniciales Obligatorios
SIEMPRE completa estos pasos antes de implementar la navegación:
// Paso 1: Identifica tu estructura de navegación
// Pregunta: ¿Pila única? ¿Varias columnas? ¿Basada en pestañas con navegación por pestaña?
// Registra la respuesta antes de escribir cualquier código
// Paso 2: Elige el contenedor basado en la estructura
// Pila única (principalmente iPhone): NavigationStack
// Varias columnas (principalmente iPad/Mac): NavigationSplitView
// Basada en pestañas: TabView con NavigationStack por pestaña
// Paso 3: Define tus tipos de valor para la navegación
// Todos los valores empujados en NavigationStack deben ser Hashable
// Para enlaces profundos/restauración, también Codable
struct Recipe: Hashable, Codable, Identifiable { ... }
// Paso 4: Planifica URLs de enlaces profundos (si es necesario)
// miapp://receta/{id}
// miapp://categoria/{nombre}/receta/{id}
// Paso 5: Planifica la restauración de estado (si es necesario)
// ¿Usarás SceneStorage? ¿Qué datos deben ser Codable?
Árbol de Decisión Rápido
¿Necesitas navegación?
├─ ¿Interfaz de varias columnas (principalmente iPad/Mac)?
│ └─ NavigationSplitView
│ ├─ ¿Necesitas profundización en la columna de detalle?
│ │ └─ NavigationStack dentro del detalle (Patrón 3)
│ └─ ¿Solo selección en el detalle?
│ └─ Solo enlace de selección (Patrón 2)
├─ ¿Aplicación basada en pestañas?
│ └─ TabView
│ ├─ ¿Cada pestaña necesita profundización?
│ │ └─ NavigationStack por pestaña (Patrón 4)
│ └─ ¿Experiencia de barra lateral en iPad?
│ └─ .tabViewStyle(.sidebarAdaptable) (Patrón 5)
└─ ¿Pila de una sola columna?
└─ NavigationStack
├─ ¿Necesitas enlaces profundos?
│ └─ Usa NavigationPath (Patrón 1b)
└─ ¿Push/pop simple?
└─ Ruta de array tipado (Patrón 1a)
¿Necesitas restauración de estado?
└─ SceneStorage + NavigationPath Codable (Patrón 6)
¿Necesitas abstracción de coordinador?
├─ ¿Flujos condicionales complejos?
├─ ¿Pruebas de lógica de navegación necesarias?
├─ ¿Compartir navegación entre muchas pantallas?
└─ SÍ a cualquier → Patrón de Router (Patrón 7)
NO a todo → Usa NavigationPath directamente
Patrón 1a: NavigationStack Básico
Cuándo: Navegación simple push/pop, todos los destinos del mismo tipo
Tiempo estimado: 5-10 min
struct RecipeList: View {
@State private var path: [Recipe] = []
var body: some View {
NavigationStack(path: $path) {
List(recipes) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle("Recetas")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
// Navegación programática
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func popToRoot() {
path.removeAll()
}
}
Puntos clave:
- Array tipado
[Recipe]cuando todos los valores son del mismo tipo NavigationLink(title, value:)basado en valornavigationDestination(for:)fuera de contenedores perezosos
Patrón 1b: NavigationStack con Enlaces Profundos
Cuándo: Múltiples tipos de destino, enlaces profundos basados en URL
Tiempo estimado: 15-20 min
struct ContentView: View {
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
HomeView()
.navigationDestination(for: Category.self) { category in
CategoryView(category: category)
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
.onOpenURL { url in
handleDeepLink(url)
}
}
func handleDeepLink(_ url: URL) {
// URL: miapp://categoria/postres/receta/tarta-de-manzana
path.removeLast(path.count) // Pop a la raíz primero
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return }
let segments = components.path.split(separator: "/").map(String.init)
var index = 0
while index < segments.count - 1 {
switch segments[index] {
case "categoria":
if let category = Category(rawValue: segments[index + 1]) {
path.append(category)
}
index += 2
case "receta":
if let recipe = dataModel.recipe(named: segments[index + 1]) {
path.append(recipe)
}
index += 2
default:
index += 1
}
}
}
}
Puntos clave:
NavigationPathpara tipos heterogéneos- Pop a la raíz antes de construir la ruta del enlace profundo
- Construye la ruta en el orden correcto (padre → hijo)
Patrón 2: NavigationSplitView Basado en Selección
Cuándo: Diseño de varias columnas donde el detalle muestra el elemento seleccionado
Tiempo estimado: 10-15 min
struct MultiColumnView: View {
@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Categorías")
} content: {
if let category = selectedCategory {
List(recipes(in: category), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle(category.name)
} else {
Text("Selecciona una categoría")
}
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Selecciona una receta")
}
}
}
}
Puntos clave:
selection: $bindingen List se conecta a la selección de columna- Los enlaces que presentan valor actualizan la selección automáticamente
- Se adapta a una sola pila en iPhone
Patrón 3: NavigationSplitView con Pila en el Detalle
Cuándo: Varias columnas con capacidad de profundización en el detalle
Tiempo estimado: 20-25 min
struct GridWithDrillDown: View {
@State private var selectedCategory: Category?
@State private var path: [Recipe] = []
var body: some View {
NavigationSplitView {
List(Category.allCases, selection: $selectedCategory) { category in
NavigationLink(category.name, value: category)
}
.navigationTitle("Categorías")
} detail: {
NavigationStack(path: $path) {
if let category = selectedCategory {
RecipeGrid(category: category)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
} else {
Text("Selecciona una categoría")
}
}
}
}
}
Puntos clave:
- NavigationStack dentro de la columna de detalle
- Grid → Profundización en detalle mientras se preserva la barra lateral
- Ruta separada para profundización, selección para barra lateral
Patrón 4: TabView con NavigationStack por Pestaña
Cuándo: Aplicación basada en pestañas donde cada pestaña tiene su propia navegación
Tiempo estimado: 15-20 min
struct TabBasedApp: View {
var body: some View {
TabView {
Tab("Inicio", systemImage: "house") {
NavigationStack {
HomeView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
}
Tab("Buscar", systemImage: "magnifyingglass") {
NavigationStack {
SearchView()
}
}
Tab("Ajustes", systemImage: "gear") {
NavigationStack {
SettingsView()
}
}
}
}
}
Puntos clave:
- Cada pestaña tiene su propio NavigationStack
- El estado de navegación se preserva al cambiar de pestaña
- Sintaxis de Tab en iOS 18+ con systemImage
Patrón 5: TabView Adaptable con Barra Lateral (iOS 18+)
Cuándo: Barra de pestañas en iPhone, barra lateral en iPad
Tiempo estimado: 20-25 min
struct AdaptableApp: View {
var body: some View {
TabView {
Tab("Ver Ahora", systemImage: "play") {
WatchNowView()
}
Tab("Biblioteca", systemImage: "books.vertical") {
LibraryView()
}
TabSection("Colecciones") {
Tab("Favoritos", systemImage: "star") {
FavoritesView()
}
Tab("Recién Añadido", systemImage: "clock") {
RecentView()
}
}
Tab(role: .search) {
SearchView()
}
}
.tabViewStyle(.sidebarAdaptable)
}
}
Puntos clave:
.tabViewStyle(.sidebarAdaptable)habilita la barra lateral en iPadTabSectioncrea grupos colapsables en la barra lateralTab(role: .search)obtiene una ubicación especial