Referência da API de Navegação SwiftUI
Visão Geral
As APIs de navegação do SwiftUI fornecem navegação orientada a dados e programática que escala de pilhas simples a layouts complexos de múltiplas colunas. Introduzidas no iOS 16 (2022) com NavigationStack e NavigationSplitView, evoluíram no iOS 18 (2024) com a unificação de Abas/Barras Laterais, e foram refinadas no iOS 26 (2025) com o design Liquid Glass.
Linha do tempo da evolução
- 2022 (iOS 16) NavigationStack, NavigationSplitView, NavigationPath, NavigationLink baseado em valor
- 2024 (iOS 18) Unificação de Abas/Barras Laterais, estilo sidebarAdaptable, transição de navegação com zoom
- 2025 (iOS 26) Chrome de navegação Liquid Glass, pesquisa alinhada à parte inferior, barras de abas flutuantes, backgroundExtensionEffect
Principais capacidades
- Navegação orientada a dados NavigationPath representa o estado da pilha, permitindo push/pop programático e deep linking
- Layouts multi-coluna NavigationSplitView adapta-se automaticamente (3 colunas no iPad → pilha única no iPhone)
- Restauração de estado NavigationPath Codable + SceneStorage para persistência entre inicializações do aplicativo
- Integração com abas NavigationStack por aba com preservação de estado ao alternar abas (iOS 18+)
- Liquid Glass Barras de navegação, barras laterais e barras de ferramentas em vidro automáticas (iOS 26+)
Quando usar vs UIKit
- Navegação SwiftUI Novos aplicativos, multiplataforma, fluxos de navegação mais simples → Use NavigationStack/SplitView
- UINavigationController Padrões de coordenador complexos, código legado, recursos específicos do UIKit → Considere UIKit
Skills Relacionados
- Use
axiom-swiftui-navpara anti-padrões, árvores de decisão, cenários de pressão - Use
axiom-swiftui-nav-diagpara solução sistemática de problemas de navegação
Quando Usar Este Skill
Use este skill quando:
- Implementando APIs de navegação NavigationStack, NavigationSplitView, NavigationPath, Tab+Navigation
- Deep linking ou restauração de estado Roteamento de URL, NavigationPath Codable, SceneStorage
- Adotando recursos do iOS 26+ Navegação Liquid Glass, pesquisa alinhada à parte inferior, minimização da barra de abas
- Escolhendo arquitetura de navegação Pilha vs SplitView vs padrões de coordenador
Evolução da API
Linha do tempo
| Ano | Versão do iOS | Principais Recursos |
|---|---|---|
| 2020 | iOS 14 | NavigationView (depreciado no iOS 16) |
| 2022 | iOS 16 | NavigationStack, NavigationSplitView, NavigationPath, NavigationLink baseado em valor |
| 2024 | iOS 18 | Unificação de Abas/Barras Laterais, sidebarAdaptable, TabSection, transições com zoom |
| 2025 | iOS 26 | Navegação Liquid Glass, backgroundExtensionEffect, tabBarMinimizeBehavior |
NavigationView (Depreciado)
NavigationView foi depreciado a partir do iOS 16. Use NavigationStack (push/pop de coluna única) ou NavigationSplitView (multi-coluna) exclusivamente em código novo. Principais melhorias: NavigationPath único substitui bindings isActive por link, segurança de tipo baseada em valor, restauração de estado Codable integrada. Consulte a documentação "Migrando para novos tipos de navegação".
Referência Completa do NavigationStack
NavigationStack representa uma interface push-pop como Ajustes no iPhone ou Configurações do Sistema no macOS.
1.1 Criando 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)
}
}
Com Binding de Caminho (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)
}
}
Binding de caminho + NavigationLink de apresentação de valor + navigationDestination(for:) formam o padrão central de navegação orientada a dados.
1.2 NavigationLink (Baseado em Valor)
NavigationLink de Apresentação de Valor
// Correto: Baseado em valor (iOS 16+)
NavigationLink(recipe.name, value: recipe)
// Correto: Com rótulo personalizado
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
// Depreciado: Baseado em visualização (iOS 13-15)
NavigationLink(recipe.name) {
RecipeDetail(recipe: recipe) // Não use em código novo
}
Como NavigationLink funciona com NavigationStack
- NavigationStack mantém uma coleção
path - Tocar em um link de apresentação de valor adiciona o valor ao caminho
- NavigationStack mapeia modificadores
navigationDestinationsobre os valores do caminho - As visualizações são empurradas para a pilha com base nos mapeamentos de destino
1.3 Modificador navigationDestination
Tipo Único
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
Múltiplos 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-Padrões de Navegação
- Nunca misture
navigationDestination(for:)eNavigationLink(destination:)na mesma hierarquia NavigationStack — causa comportamento indefinido - Registre
navigationDestination(for:)uma vez por tipo de dado — duplicatas fazem a visualização errada aparecer
Regras de posicionamento
- Coloque
navigationDestinationfora de contêineres lazy (não dentro de ForEach) - Coloque perto de NavigationLinks relacionados para organização do código
- Deve estar dentro da hierarquia NavigationStack
// Correto: Fora do contêiner lazy
ScrollView {
LazyVGrid(columns: columns) {
ForEach(recipes) { recipe in
NavigationLink(value: recipe) {
RecipeTile(recipe: recipe)
}
}
}
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
// Errado: Dentro de ForEach (pode não ser carregado)
ForEach(recipes) { recipe in
NavigationLink(value: recipe) { RecipeTile(recipe: recipe) }
.navigationDestination(for: Recipe.self) { r in // Não faça isso
RecipeDetail(recipe: r)
}
}
1.4 NavigationPath
NavigationPath é uma coleção type-erased para pilhas de navegação heterogêneas.
Array Tipado vs NavigationPath
// Array tipado: Todos os valores do mesmo tipo
@State private var path: [Recipe] = []
// NavigationPath: Tipos mistos
@State private var path = NavigationPath()
Operações NavigationPath
// Adicionar valor
path.append(recipe)
// Voltar ao anterior
path.removeLast()
// Voltar à raiz
path.removeLast(path.count)
// ou
path = NavigationPath()
// Verificar contagem
if path.count > 0 { ... }
// Deep link: Definir vários valores
path.append(category)
path.append(recipe)
Suporte Codable
// NavigationPath é Codable quando todos os valores são 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)
Referência Completa do NavigationSplitView
NavigationSplitView cria layouts multi-coluna que se adaptam ao tamanho do dispositivo.
2.1 Layout de Duas Colunas
Duas Colunas Básico (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 Layout de Três Colunas
Adicione um closure content: entre a barra lateral e o detalhe para uma coluna do meio:
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 com NavigationStack
Coloque um NavigationStack(path:) dentro da coluna de detalhes para drill-down de grade para detalhe enquanto preserva a seleção da 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 Visibilidade da Coluna
@State private var columnVisibility: NavigationSplitViewVisibility = .all
NavigationSplitView(columnVisibility: $columnVisibility) {
Sidebar()
} content: {
Content()
} detail: {
Detail()
}
// Controlar visibilidade programaticamente
columnVisibility = .detailOnly // Ocultar barra lateral e conteúdo
columnVisibility = .all // Mostrar todas as colunas
columnVisibility = .automatic // O sistema decide
2.5 Adaptação Automática
NavigationSplitView adapta-se automaticamente:
- iPad paisagem Todas as colunas visíveis (dependendo da configuração)
- iPad retrato/Slide Over Recolhe para sobreposição ou coluna única
- iPhone Pilha de navegação única
- Apple Watch/TV Pilha de navegação única
As mudanças de seleção traduzem-se automaticamente em push/pop no iPhone.
2.6 Barra Lateral Liquid Glass iOS 26+ (WWDC 2025, 323)
NavigationSplitView {
List { ... }
} detail: {
DetailView()
}
// A barra lateral recebe automaticamente aparência Liquid Glass no iPad/macOS
// Estender conteúdo atrás da barra lateral de vidro
.backgroundExtensionEffect() // Espelha e desfoca o conteúdo fora da área segura
Deep Linking e Roteamento de URL
3.1 Padrão de Deep Link
Use .onOpenURL para receber URLs, analise com URLComponents, depois manipule NavigationPath:
.onOpenURL { url in
guard let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let host = components.host else { return }
path.removeLast(path.count) // Primeiro, volte à raiz
// Analise host/caminho para determinar o destino, depois path.append(valor)
}
Para deep links de múltiplas etapas (myapp://category/desserts/recipe/apple-pie), itere pelos componentes do caminho da URL e anexe cada valor resolvido para construir a pilha de navegação completa.
Para exemplos abrangentes de deep linking, diagnóstico de erros e fluxos de trabalho de teste, consulte axiom-swiftui-nav-diag (Padrão 3).
Restauração de Estado
4.1 Restauração 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 ao aparecer
if let data = data {
navModel.jsonData = data
}
// Salvar em alterações
for await _ in navModel.objectWillChangeSequence {
data = navModel.jsonData
}
}
.environmentObject(dataModel)
}
}
4.2 NavigationModel Codable
class NavigationModel: ObservableObject, Codable {
@Published var selectedCategory: Category?
@Published var recipePath: [Recipe] = []
enum CodingKeys: String, CodingKey {
case selectedCategory
case recipePathIds // Armazene IDs, não 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] } // Descarta itens deletados
}
}
Armazene IDs (não objetos de modelo completos) e use compactMap para lidar graciosamente com itens deletados. Adicione a propriedade computada jsonData e objectWillChangeSequence para integração SceneStorage conforme mostrado em 4.1.
Integração Tab + Navegação
5.1 Sintaxe de Aba (iOS 18+) (WWDC 2024, 4:27)
TabView {
Tab("Watch Now", systemImage: "play") {
WatchNowView()
}
Tab("Library", systemImage: "books.vertical") {
LibraryView()
…
[truncado para tradução]