NavigationLink — qué es, botón de transición en SwiftUI

¿Qué es NavigationLink en SwiftUI?

NavigationLink es una View que inicia una transición de navegación al presionarla. Dentro de NavigationStack, al presionar NavigationLink coloca la pantalla de destino en la pila y muestra el botón de Atrás del sistema. NavigationLink existe desde iOS 13 y es el método principal de navegación del usuario en SwiftUI.

NavigationLink no hereda de UIButton — es una View de SwiftUI que se adapta automáticamente al contexto. Dentro de List, NavigationLink se muestra con un indicador de divulgación. Fuera de una lista, NavigationLink se comporta como un botón normal pero con comportamiento de navegación.

Según SwiftUI Lab (2024), NavigationLink es una de las Views más usadas en aplicaciones SwiftUI, solo superada por Text, Image y VStack. Comprender las diferencias entre las formas de inicialización es crítico para el rendimiento y el comportamiento predecible de la navegación.

Cómo funciona NavigationLink internamente

Al presionarlo, NavigationLink agrega un valor (o destination) a la pila de navegación asociada con el NavigationStack o NavigationView más cercano. SwiftUI usa EnvironmentValue para pasar la ruta de navegación a través de la jerarquía de Views. NavigationLink lee esta ruta del Environment y la modifica al presionarlo.

Formas de inicialización de NavigationLink

NavigationLink tiene dos formas principales: con destination (especificando directamente la View de destino) y con value (valor para NavigationDestination). La elección de la forma depende de la versión de iOS y la arquitectura de navegación.

Forma destination (iOS 13+): NavigationLink(destination: DetailView(), label: { Text("Open") }). Esta forma crea DetailView inmediatamente al renderizar NavigationLink, incluso si el usuario no ha hecho clic en el enlace. Esto provoca una inicialización prematura de View y posibles problemas de rendimiento si la View de destino realiza operaciones pesadas en su inicializador.

Forma value (iOS 16+): NavigationLink(value: "detail_42", label: { Text("Open") }). La View de destino se crea solo cuando se presiona el enlace, cuando SwiftUI encuentra el .navigationDestination correspondiente. Esto evita la inicialización prematura y hace que la navegación sea más predecible.

NavigationLink con NavigationStack: uso correcto

NavigationLink con NavigationStack en iOS 16+ requiere cambiar a la forma value. Usted define un tipo de datos para la navegación (String, Int, enum Route) y registra el destination a través de .navigationDestination. NavigationLink solo coloca el valor en la pila, y SwiftUI crea la View de destino al presionar.

struct CatalogView: View {
    let categories: [String]

    var body: some View {
        List(categories, id: \.self) { category in
            NavigationLink(value: category) {
                Text(category)
            }
        }
        .navigationDestination(for: String.self) { category in
            CategoryView(name: category)
        }
    }
}

// Programmatic navigation:
struct DeepLinkView: View {
    @State private var path: [AppRoute] = []

    var body: some View {
        NavigationStack(path: $path) {
            HomeView()
                .navigationDestination(for: AppRoute.self) { route in
                    switch route {
                    case .detail(let id): DetailView(id: id)
                    case .settings: SettingsView()
                    }
                }
                .toolbar {
                    Button("Open Settings") {
                        path.append(AppRoute.settings)
                    }
                }
        }
    }
}

Navegación programática: agregar un valor a la ruta (mediante path.append) equivale a presionar un NavigationLink con el mismo valor. Esto permite implementar navegación desde ViewModel, Coordinator o en respuesta a notificaciones push.

Forma IsActive (NavigationLink(isActive:destination:label:)) está disponible por compatibilidad, pero no se recomienda en iOS 16+. Use la forma value con Binding a un array de ruta o NavigationPath.

NavigationLink en List: características

NavigationLink en List muestra automáticamente un indicador de divulgación (chevron) en el lado derecho de la fila, señalando al usuario que presionar lo llevará a otra pantalla. List gestiona la visualización de la flecha automáticamente — a diferencia de un NavigationLink normal fuera de una lista, donde no hay flecha.

Con iOS 16, List con NavigationLink usa automáticamente la forma value dentro de List(data:rowContent:). Al usar ForEach dentro de List, el indicador de divulgación también se agrega automáticamente. Este comportamiento no se puede desactivar mediante modificadores — solo reemplazar NavigationLink con Button puede eliminar la flecha.

Problema con la forma destination en List: si usa NavigationLink(destination:label:) dentro de List, todas las Views de destino se crean inmediatamente al cargar la lista, independientemente de si el usuario hizo clic en el enlace o no. Para listas con un gran número de filas, esto puede ralentizar significativamente la carga inicial y aumentar el consumo de memoria. La forma value con NavigationStack resuelve este problema.

Según WWDC 2022 (Session 10054), Apple recomienda usar NavigationStack y la forma value de NavigationLink para proyectos nuevos. Esto es especialmente importante para List con datos dinámicos, donde el número de filas puede ser grande.

Patrones de uso de NavigationLink

Patrón 1: Apariencia personalizada de NavigationLink. NavigationLink acepta cualquier View como label, lo que permite crear diseños personalizados para el enlace. Dentro de List, esto es especialmente conveniente — obtiene un indicador de divulgación automático al usar NavigationLink.

NavigationLink(value: ProductRoute.detail(product)) {
    HStack {
        AsyncImage(url: product.imageURL)
            .frame(width: 60, height: 60)
        VStack(alignment: .leading) {
            Text(product.name).font(.headline)
            Text(product.price) .foregroundColor(.secondary)
        }
    }
    .padding(8)
}

Patrón 2: NavigationLink sin flecha (botón personalizado). Si no necesita un indicador de divulgación, use Button para navegación programática: path.append(value). Esto es útil para elementos de interfaz personalizados donde NavigationLink se ve antinatural.

Patrón 3: Navegación condicional. Puede bloquear NavigationLink usando un destination vacío o no agregando .navigationDestination para ciertos valores. La navegación programática a través de path permite verificar condiciones antes de agregar un valor.

Según Hacking with Swift (2024), la mayoría de los problemas con NavigationLink están relacionados con el uso de la forma destination en proyectos antiguos. Al migrar a NavigationStack, reemplace todos los NavigationLink(destination:label:) con NavigationLink(value:label:) y agregue .navigationDestination en el nivel raíz.