NavigationView: conceitos básicos, pilha de navegação em apps SwiftUI

O que é NavigationView?

NavigationView é um contentor SwiftUI que envolve uma hierarquia de ecrãs e fornece uma interface de navegação. Dentro do NavigationView funciona o NavigationLink — um elemento que, ao ser pressionado, substitui o ecrã atual por um novo. NavigationView adiciona automaticamente uma barra de navegação com título e botão «Voltar».

NavigationView apareceu no iOS 13 juntamente com o SwiftUI. Conceptual mente, substitui o UINavigationController do UIKit, mas é implementado declarativamente. Em vez de push/pop manual, o desenvolvedor descreve a relação entre ecrãs através do NavigationLink. O sistema gere a pilha automaticamente.

NavigationView suporta os modificadores .navigationTitle, .navigationBarTitleDisplayMode, .toolbar e .searchable. Para iOS 16+, a Apple introduziu o NavigationStack, que preserva a API do NavigationView mas adiciona gestão programática da pilha através do NavigationPath. Para projetos com suporte até iOS 15, NavigationView continua a ser a única opção.

NavigationLink e transições entre ecrãs

NavigationLink é um elemento SwiftUI que cria uma transição para um ecrã de destino dentro de NavigationView ou NavigationStack. Ao pressionar NavigationLink, o sistema adiciona o ecrã de destino à pilha de navegação. A animação de transição é o push padrão da direita no iOS, adaptando-se à plataforma.

struct ContentView: View {
    var body: some View {
        NavigationView {
            List(items) { item in
                NavigationLink(destination: DetailView(item: item)) {
                    Text(item.title)
                }
            }
            .navigationTitle("Lista")
        }
    }
}

struct DetailView: View {
    let item: Item

    var body: some View {
        VStack {
            Text(item.description)
                .navigationTitle(item.title)
                .navigationBarTitleDisplayMode(.inline)
        }
    }
}

NavigationLink aceita dois parâmetros: destination — a View de destino, e label — o elemento que o utilizador pressiona. Para listas, a sintaxe com value e NavigationLink(value:) é conveniente — desmarca automaticamente a célula e funciona com NavigationPath.

NavigationStack vs NavigationView: comparação de API

Com o iOS 16, a Apple apresentou o NavigationStack como substituto do NavigationView. NavigationStack preserva a sintaxe declarativa mas adiciona uma funcionalidade criticamente importante — gestão programática da pilha através da propriedade path do tipo NavigationPath ou de um array de Hashable.

Para projetos com versão mínima iOS 16+, use NavigationStack. Para suporte iOS 14-15 — NavigationView. NavigationStack não tem análogos diretos para versões antigas, por isso a atualização requer verificação de compatibilidade.

Toolbar e configuração do navigationTitle

Os modificadores .toolbar e .navigationTitle controlam o conteúdo da barra de navegação. .navigationTitle define o título do ecrã, .navigationBarTitleDisplayMode seleciona o estilo: .large (grande, padrão) ou .inline (compacto, como em Definições). .toolbar adiciona botões, pesquisa e controlo segmentado.

struct SettingsView: View {
    var body: some View {
        NavigationStack {
            Form {
                Section("Perfil") {
                    Text("Nome de utilizador")
                    Toggle("Notificações", isOn: $notifications)
                }
            }
            .navigationTitle("Definições")
            .navigationBarTitleDisplayMode(.large)
            .toolbar {
                ToolbarItem(placement: .navigationBarTrailing) {
                    Button("Guardar") { save() }
                }
                ToolbarItem(placement: .navigationBarLeading) {
                    EditButton()
                }
            }
        }
    }
}

.searchable é outro modificador que integra uma barra de pesquisa na barra de navegação. Funciona tanto com NavigationView como com NavigationStack. A pesquisa oculta-se automaticamente ao fazer scroll e aparece ao deslizar para baixo. Suporta filtragem de listas através de um Binding String.

Navegação programática com NavigationPath

NavigationPath é um tipo iOS 16+ que representa uma pilha de navegação como uma coleção de valores Hashable. O desenvolvedor adiciona elementos ao path para transições programáticas e remove-os para retroceder. NavigationPath suporta deep links, notificações push e restauração de estado.

struct AppNavigation: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List(categories) { category in
                NavigationLink("Categoria \(category.name)",
                               value: category)
            }
            .navigationTitle("Categorias")
            .navigationDestination(for: Category.self) { category in
                ProductListView(category: category)
            }
            .navigationDestination(for: Product.self) { product in
                ProductDetailView(product: product)
            }
        }

        // Navegação programática por deep link
        .onOpenURL { url in
            guard let productId = DeepLinkParser.parse(url) else { return }
            path.append(Product(id: productId))
        }
    }
}

.navigationDestination(for:) regista um tipo de dados para o qual mostrar um ecrã. Quando um valor deste tipo é adicionado ao path, o sistema cria automaticamente a View de destino. Esta abordagem substitui o NavigationLink(destination:) explícito e torna a navegação estritamente tipada.

NavigationView no iPad, watchOS e tvOS

NavigationView e NavigationStack funcionam em todas as plataformas Apple: iOS, iPadOS, watchOS, tvOS e macOS. O comportamento adapta-se ao ecrã. No iPad, NavigationStack suporta NavigationSplitView, que substitui o UISplitViewController do UIKit e exibe duas colunas num ecrã largo.

NavigationSplitView (iOS 16+) divide o ecrã em barra lateral (lista) e detalhe. No iPhone, a barra lateral fica oculta, mostrando apenas o detalhe através de NavigationLink. No iPad, a barra lateral e o detalhe são exibidos simultaneamente em modo split.

struct AdaptiveNavigation: View {
    @State private var selectedCategory: Category?

    var body: some View {
        NavigationSplitView {
            List(categories, selection: $selectedCategory) { category in
                Text(category.name)
            }
            .navigationTitle("Categorias")
        } detail: {
            ProductListView(category: selectedCategory)
        }
    }
}

NavigationSplitView seleciona automaticamente o modo de visualização ideal para cada dispositivo. No iPhone em retrato — pilha, no iPad e iPhone em paisagem — split. O desenvolvedor não precisa escrever código separado para diferentes classes de tamanho.