NavigationLink — cos'è, pulsante di transizione in SwiftUI

Cos'è NavigationLink in SwiftUI?

NavigationLink è una View che avvia una transizione di navigazione quando viene premuta. All'interno di NavigationStack, premere NavigationLink inserisce la schermata di destinazione nello stack e mostra il pulsante Indietro di sistema. NavigationLink esiste da iOS 13 ed è il metodo principale di navigazione utente in SwiftUI.

NavigationLink non eredita da UIButton — è una View SwiftUI che si adatta automaticamente al contesto. All'interno di List, NavigationLink viene visualizzato con un indicatore di divulgazione. Al di fuori di una lista, NavigationLink si comporta come un pulsante normale ma con comportamento di navigazione.

Secondo SwiftUI Lab (2024), NavigationLink è una delle View più utilizzate nelle applicazioni SwiftUI, seconda solo a Text, Image e VStack. Comprendere le differenze tra le forme di inizializzazione è fondamentale per le prestazioni e un comportamento di navigazione prevedibile.

Come funziona NavigationLink internamente

Quando viene premuto, NavigationLink aggiunge un valore (o destination) allo stack di navigazione associato al NavigationStack o NavigationView più vicino. SwiftUI utilizza EnvironmentValue per passare il percorso di navigazione attraverso la gerarchia delle View. NavigationLink legge questo percorso dall'Environment e lo modifica quando viene premuto.

Forme di inizializzazione di NavigationLink

NavigationLink ha due forme principali: con destination (specificando direttamente la View di destinazione) e con value (valore per NavigationDestination). La scelta della forma dipende dalla versione di iOS e dall'architettura di navigazione.

Forma destination (iOS 13+): NavigationLink(destination: DetailView(), label: { Text("Open") }). Questa forma crea DetailView immediatamente quando si esegue il rendering di NavigationLink, anche se l'utente non ha fatto clic sul collegamento. Ciò porta a un'inizializzazione prematura della View e a potenziali problemi di prestazioni se la View di destinazione esegue operazioni pesanti nel suo inizializzatore.

Forma value (iOS 16+): NavigationLink(value: "detail_42", label: { Text("Open") }). La View di destinazione viene creata solo quando il collegamento viene premuto, quando SwiftUI trova il corrispondente .navigationDestination. Ciò impedisce l'inizializzazione prematura e rende la navigazione più prevedibile.

NavigationLink con NavigationStack: uso corretto

NavigationLink con NavigationStack in iOS 16+ richiede il passaggio alla forma value. Si definisce un tipo di dati per la navigazione (String, Int, enum Route) e si registra la destinazione tramite .navigationDestination. NavigationLink inserisce solo il valore nello stack e SwiftUI crea la View di destinazione quando viene premuto.

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)
                    }
                }
        }
    }
}

Navigazione programmatica: aggiungere un valore al percorso (tramite path.append) equivale a premere un NavigationLink con lo stesso valore. Ciò consente di implementare la navigazione da ViewModel, Coordinator o in risposta a notifiche push.

Forma IsActive (NavigationLink(isActive:destination:label:)) è disponibile per compatibilità ma non è raccomandata in iOS 16+. Utilizzare la forma value con Binding su un array di percorso o NavigationPath.

NavigationLink in List: caratteristiche

NavigationLink in List mostra automaticamente un indicatore di divulgazione (chevron) sul lato destro della riga, segnalando all'utente che la pressione porterà a un'altra schermata. List gestisce automaticamente la visualizzazione della freccia — a differenza di un NavigationLink normale al di fuori di una lista, dove non c'è freccia.

Con iOS 16, List con NavigationLink utilizza automaticamente la forma value all'interno di List(data:rowContent:). Quando si utilizza ForEach all'interno di List, anche l'indicatore di divulgazione viene aggiunto automaticamente. Questo comportamento non può essere disabilitato tramite modificatori — solo la sostituzione di NavigationLink con Button può rimuovere la freccia.

Problema con la forma destination in List: se si utilizza NavigationLink(destination:label:) all'interno di List, tutte le View di destinazione vengono create immediatamente al caricamento della lista, indipendentemente dal fatto che l'utente abbia fatto clic sul collegamento o meno. Per le liste con un gran numero di righe, ciò può rallentare significativamente il caricamento iniziale e aumentare il consumo di memoria. La forma value con NavigationStack risolve questo problema.

Secondo WWDC 2022 (Session 10054), Apple raccomanda di utilizzare NavigationStack e la forma value di NavigationLink per i nuovi progetti. Ciò è particolarmente importante per List con dati dinamici, dove il numero di righe può essere elevato.

Pattern di utilizzo di NavigationLink

Pattern 1: Aspetto personalizzato di NavigationLink. NavigationLink accetta qualsiasi View come etichetta, consentendo di creare design personalizzati per il collegamento. All'interno di List, questo è particolarmente conveniente — si ottiene un indicatore di divulgazione automatico quando si utilizza 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)
}

Pattern 2: NavigationLink senza freccia (pulsante personalizzato). Se non si necessita di un indicatore di divulgazione, utilizzare Button per la navigazione programmatica: path.append(value). Ciò è utile per elementi di interfaccia personalizzati dove NavigationLink appare innaturale.

Pattern 3: Navigazione condizionale. È possibile bloccare NavigationLink utilizzando una destinazione vuota o non aggiungendo .navigationDestination per determinati valori. La navigazione programmatica tramite percorso consente di verificare le condizioni prima di aggiungere un valore.

Secondo Hacking with Swift (2024), la maggior parte dei problemi con NavigationLink sono legati all'uso della forma destination in progetti precedenti. Durante la migrazione a NavigationStack, sostituire tutti i NavigationLink(destination:label:) con NavigationLink(value:label:) e aggiungere .navigationDestination a livello radice.