Navegação SwiftUI
Quando usar este skill
Use quando:
- Escolher arquitetura de navegação (NavigationStack vs NavigationSplitView vs TabView)
- Implementar navegação programática com NavigationPath
- Configurar deep linking e roteamento de URLs
- Implementar restauração de estado para navegação
- Adotar padrões de Abas/Sidebar (iOS 18+)
- Implementar padrões de coordenador/roteador
- Solicitar revisão de código de implementação de navegação antes de enviar
Skills relacionados
- Use
axiom-swiftui-nav-diagpara solução de problemas sistemática de falhas de navegação - Use
axiom-swiftui-nav-refpara referência de API abrangente (incluindo personalização de Abas, recursos do iOS 26+) com todos os exemplos da WWDC
Exemplos de prompts
Estas são perguntas reais que desenvolvedores fazem e que este skill foi projetado para responder:
1. "Devo usar NavigationStack ou NavigationSplitView para meu aplicativo?"
-> O skill fornece uma árvore de decisão baseada em dispositivos alvo, profundidade da hierarquia de conteúdo e requisitos multiplataforma
2. "Como navegar programaticamente em SwiftUI?"
-> O skill mostra padrões de manipulação de NavigationPath para push, pop, pop-to-root e deep linking
3. "Meus deep links não estão funcionando. O app abre, mas mostra a tela errada."
-> O skill cobre padrões de análise de URL, ordem de construção do caminho e problemas de temporização com onOpenURL
4. "O estado de navegação é perdido quando meu app vai para segundo plano."
-> O skill demonstra NavigationPath Codable, persistência com SceneStorage e restauração resistente a falhas
5. "Como implementar um padrão de coordenador em SwiftUI?"
-> O skill fornece exemplos de padrão Router junto com orientação sobre quando coordenadores agregam valor vs complexidade
Bandeiras Vermelhas — Antípadas a Prevenir
Se você está fazendo QUALQUER uma destas coisas, PARE e use os padrões deste skill:
❌ CRÍTICO — Nunca Faça Isso
1. Usar NavigationView obsoleto no iOS 16+
// ❌ ERRADO — Obsoleto, comportamento diferente no iOS 16+
NavigationView {
List { ... }
}
.navigationViewStyle(.stack)
Por que isso falha NavigationView está obsoleto desde o iOS 16. Ele não suporta NavigationPath, tornando a navegação programática e deep linking não confiáveis. Comportamento diferente entre versões do iOS causa bugs.
2. Usar NavigationLink baseado em view para navegação programática
// ❌ ERRADO — Não pode ser controlado programaticamente
NavigationLink("Recipe") {
RecipeDetail(recipe: recipe) // Destino de view, sem valor
}
Por que isso falha Links baseados em view não podem ser controlados programaticamente. Não há como fazer deep link ou pop para esse destino. Obsoleto desde o iOS 16.
3. Colocar navigationDestination dentro de containers lentos
// ❌ ERRADO — Pode não ser carregado quando necessário
LazyVGrid(columns: columns) {
ForEach(items) { item in
NavigationLink(value: item) { ... }
.navigationDestination(for: Item.self) { item in // Não faça isso
ItemDetail(item: item)
}
}
}
Por que isso falha Containers lentos não carregam todas as views imediatamente. navigationDestination pode não estar visível para NavigationStack, causando falha silenciosa na navegação.
4. Armazenar objetos de modelo completos no NavigationPath para restauração
// ❌ ERRADO — Duplica dados, obsoleto na restauração
class NavigationModel: Codable {
var path: [Recipe] = [] // Objetos Recipe completos
}
Por que isso falha Duplica dados já existentes no seu modelo. Na restauração, os dados de Recipe podem estar obsoletos (editados/excluídos em outro lugar). Use IDs e resolva para dados atuais.
5. Modificar NavigationPath fora do MainActor
// ❌ ERRADO — Atualização de UI fora da thread principal
Task.detached {
await viewModel.path.append(recipe) // Thread de segundo plano
}
Por que isso falha NavigationPath está vinculado à UI. Modificações devem ocorrer no MainActor ou o estado de navegação se torna corrompido. Pode causar falhas ou erros silenciosos.
6. Isolamento @MainActor ausente para estado de navegação
// ❌ ERRADO — Não isolado com MainActor
class Router: ObservableObject {
@Published var path = NavigationPath() // Sem @MainActor
}
Por que isso falha Em concorrência estrita do Swift 6, propriedades @Published acessadas de views SwiftUI requerem isolamento com MainActor. Causa avisos de corrida de dados e potenciais falhas.
7. Não tratar estado de navegação em apps com múltiplas abas
// ❌ ERRADO — NavigationPath compartilhado entre abas
TabView {
Tab("Home") { HomeView() }
Tab("Settings") { SettingsView() }
}
// Todas as abas compartilham o mesmo NavigationStack — errado!
Por que isso falha Cada aba deve ter seu próprio NavigationStack para preservar o estado de navegação ao alternar abas. Estado compartilhado causa UX confusa.
8. Ignorar erros de decodificação de NavigationPath
// ❌ ERRADO — Falha em dados inválidos
let path = NavigationPath(try! decoder.decode(NavigationPath.CodableRepresentation.self, from: data))
Por que isso falha O usuário pode ter excluído itens que estavam no caminho. O esquema pode ter mudado. Force unwrap causa falha na restauração.
Primeiros Passos Obrigatórios
SEMPRE complete estas etapas antes de implementar navegação:
// Etapa 1: Identifique sua estrutura de navegação
// Pergunte: Pilha única? Multi-coluna? Baseado em abas com navegação por aba?
// Registre a resposta antes de escrever qualquer código
// Etapa 2: Escolha o container com base na estrutura
// Pilha única (iPhone primário): NavigationStack
// Multi-coluna (iPad/Mac primário): NavigationSplitView
// Baseado em abas: TabView com NavigationStack por aba
// Etapa 3: Defina seus tipos de valor para navegação
// Todos os valores empurrados no NavigationStack devem ser Hashable
// Para deep linking/restauração, também Codable
struct Recipe: Hashable, Codable, Identifiable { ... }
// Etapa 4: Planeje URLs de deep link (se necessário)
// myapp://recipe/{id}
// myapp://category/{name}/recipe/{id}
// Etapa 5: Planeje restauração de estado (se necessário)
// Você usará SceneStorage? Quais dados devem ser Codable?
Árvore de Decisão Rápida
Precisa de navegação?
├─ Interface multi-coluna (iPad/Mac primário)?
│ └─ NavigationSplitView
│ ├─ Precisa de drill-down na coluna de detalhes?
│ │ └─ NavigationStack dentro do detalhe (Padrão 3)
│ └─ Detalhe apenas com seleção?
│ └─ Apenas binding de seleção (Padrão 2)
├─ App baseado em abas?
│ └─ TabView
│ ├─ Cada aba precisa de drill-down?
│ │ └─ NavigationStack por aba (Padrão 4)
│ └─ Experiência de sidebar no iPad?
│ └─ .tabViewStyle(.sidebarAdaptable) (Padrão 5)
└─ Pilha única?
└─ NavigationStack
├─ Precisa de deep linking?
│ └─ Use NavigationPath (Padrão 1b)
└─ Push/pop simples?
└─ Array tipado de caminho (Padrão 1a)
Precisa de restauração de estado?
└─ SceneStorage + NavigationPath Codable (Padrão 6)
Precisa de abstração de coordenador?
├─ Fluxos condicionais complexos?
├─ Teste de lógica de navegação necessário?
├─ Compartilhar navegação por muitas telas?
└─ SIM para qualquer um → Padrão Router (Padrão 7)
NÃO para todos → Use NavigationPath diretamente
Padrão 1a: NavigationStack Básico
Quando: Navegação push/pop simples, todos os destinos do mesmo tipo
Custo de tempo: 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("Recipes")
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
}
// Navegação programática
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func popToRoot() {
path.removeAll()
}
}
Pontos chave:
- Array tipado
[Recipe]quando todos valores são do mesmo tipo NavigationLink(title, value:)baseado em valornavigationDestination(for:)fora de containers lentos
Padrão 1b: NavigationStack com Deep Linking
Quando: Múltiplos tipos de destino, deep linking baseado em URL
Custo de tempo: 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: myapp://category/desserts/recipe/apple-pie
path.removeLast(path.count) // Pop to root primeiro
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 "category":
if let category = Category(rawValue: segments[index + 1]) {
path.append(category)
}
index += 2
case "recipe":
if let recipe = dataModel.recipe(named: segments[index + 1]) {
path.append(recipe)
}
index += 2
default:
index += 1
}
}
}
}
Pontos chave:
NavigationPathpara tipos heterogêneos- Pop to root antes de construir o caminho de deep link
- Construir caminho na ordem correta (pai → filho)
Padrão 2: NavigationSplitView Baseado em Seleção
Quando: Layout multi-coluna onde o detalhe mostra o item selecionado
Custo de tempo: 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("Categories")
} content: {
if let category = selectedCategory {
List(recipes(in: category), selection: $selectedRecipe) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationTitle(category.name)
} else {
Text("Selecione uma categoria")
}
} detail: {
if let recipe = selectedRecipe {
RecipeDetail(recipe: recipe)
} else {
Text("Selecione uma receita")
}
}
}
}
Pontos chave:
selection: $bindingno List conecta à seleção da coluna- Links que apresentam valores atualizam a seleção automaticamente
- Adapta-se para pilha única no iPhone
Padrão 3: NavigationSplitView com Stack no Detalhe
Quando: Multi-coluna com capacidade de drill-down no detalhe
Custo de tempo: 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("Categories")
} detail: {
NavigationStack(path: $path) {
if let category = selectedCategory {
RecipeGrid(category: category)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
} else {
Text("Selecione uma categoria")
}
}
}
}
}
Pontos chave:
- NavigationStack dentro da coluna de detalhes
- Drill-down Grid → Detalhe preservando a sidebar
- Caminho separado para drill-down, seleção para sidebar
Padrão 4: TabView com NavigationStack por Aba
Quando: App baseado em abas onde cada aba tem sua própria navegação
Custo de tempo: 15-20 min
struct TabBasedApp: View {
var body: some View {
TabView {
Tab("Home", systemImage: "house") {
NavigationStack {
HomeView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
}
Tab("Buscar", systemImage: "magnifyingglass") {
NavigationStack {
SearchView()
}
}
Tab("Configurações", systemImage: "gear") {
NavigationStack {
SettingsView()
}
}
}
}
}
Pontos chave:
- Cada aba tem seu próprio NavigationStack
- Estado de navegação preservado ao alternar abas
- Sintaxe de Tab do iOS 18+ com systemImage
Padrão 5: TabView Adaptável com Sidebar (iOS 18+)
Quando: Barra de abas no iPhone, sidebar no iPad
Custo de tempo: 20-25 min
struct AdaptableApp: View {
var body: some View {
TabView {
Tab("Assistir Agora", systemImage: "play") {
WatchNowView()
}
Tab("Biblioteca", systemImage: "books.vertical") {
LibraryView()
}
TabSection("Coleções") {
Tab("Favoritos", systemImage: "star") {
FavoritesView()
}
Tab("Adicionados Recentemente", systemImage: "clock") {
RecentView()
}
}
Tab(role: .search) {
SearchView()
}
}
.tabViewStyle(.sidebarAdaptable)
}
}
Pontos chave:
.tabViewStyle(.sidebarAdaptable)habilita sidebar no iPadTabSectioncria grupos recolhíveis na sidebarTab(role: .search)obtém posicionamento especial
Padrão 6: Restauração de Estado com SceneStorage
Quando: Preservar estado de navegação entre lançamentos do app
Custo de tempo: 25-30 min
struct StateRestorationApp: View {
@SceneStorage("navigationPath") private var navigationPathData: Data?
@State private var path = NavigationPath()
var body: some View {
NavigationStack(path: $path) {
ContentView()
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item)
}
}
.onAppear {
restorePath()
}
.onChange(of: path.codable) { _, newValue in
savePath(newValue)
}
}
private func restorePath() {
guard let data = navigationPathData else { return }
do {
let representation = try JSONDecoder().decode(
NavigationPath.CodableRepresentation.self,
from: data
)
path = NavigationPath(representation)
} catch {
// Falha na restauração: pode ocorrer se dados mudaram entre versões
print("Restauração de path falhou: \(error)")
navigationPathData = nil
}
}
private func savePath(_ representation: NavigationPath.CodableRepresentation?) {
guard let representation else {
navigationPathData = nil
return
}
do {
let data = try JSONEncoder().encode(representation)
navigationPathData = data
} catch {
print("Falha ao salvar path: \(error)")
}
}
}
extension NavigationPath {
var codable: NavigationPath.CodableRepresentation? {
guard let representation = try? JSONEncoder().encode(self),
let codable = try? JSONDecoder().decode(
NavigationPath.CodableRepresentation.self,
from: representation
) else {
return nil
}
return codable
}
}
Pontos chave:
- Usa
SceneStoragepara persistência de dados pequenos - Codifica NavigationPath como CodableRepresentation
- Sempre trata erros de decodificação graciosamente
- Tamanho limitado do SceneStorage: adequado para caminhos de navegação
Padrão 7: Padrão Router para Fluxos Complexos
Quando: Lógica de navegação condicional complexa, teste ou compartilhamento entre telas
Custo de tempo: 30-40 min
@MainActor
@Observable
final class Router {
var path = NavigationPath()
func showRecipe(_ recipe: Recipe) {
path.append(recipe)
}
func showCategory(_ category: Category) {
path.append(category)
}
func handleDeepLink(_ url: URL) {
path.removeLast(path.count)
// ... lógica de análise de deep link
}
func popToRoot() {
path.removeLast(path.count)
}
}
struct RoutedApp: View {
@State private var router = Router()
var body: some View {
NavigationStack(path: $router.path) {
ContentView()
.environment(router)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
.navigationDestination(for: Category.self) { category in
CategoryView(category: category)
}
}
}
}
struct SomeDeepView: View {
@Environment(Router.self) private var router
var body: some View {
Button("Ir para Receita Específica") {
router.showRecipe(Recipe(id: "123", name: "Bolo"))
}
}
}
Pontos chave:
- Isolamento
@MainActorpara segurança com concorrência @Observablepara atualizações de UI- Encapsula lógica de navegação em um único lugar
- Útil para: teste, fluxos complexos, navegação compartilhada
Perguntas Frequentes (FAQ)
P: NavigationSplitView vs NavigationStack — Quando usar qual?
R: NavigationSplitView é para layout multi-coluna (iPad/Mac primário). NavigationStack é para pilha única (iPhone primário). Veja a Árvore de Decisão acima.
P: Posso misturar NavigationSplitView com NavigationStack?
R: Sim! Coloque NavigationStack na coluna de detalhes do NavigationSplitView para permitir drill-down (veja Padrão 3).
P: Como lidar com deep linking em um app com múltiplas abas?
R: Use um Router centralizado que gerencia todos os caminhos de navegação das abas. Cada aba verifica sua URL de deep link designada.
P: O que acontece se a decodificação do NavigationPath falhar?
R: Sempre use do-catch e redefina o caminho para vazio (popToRoot). Veja Padrão 6 para o padrão correto.
P: Preciso de um Router se meu app é simples?
R: Não. Use NavigationPath diretamente. Adicione um Router quando precisar de fluxos condicionais complexos, teste ou compartilhamento de navegação entre telas.
Guia de Migração
De NavigationView (obsoleto) para NavigationStack
// Antes (iOS 15)
NavigationView {
List(recipes) { recipe in
NavigationLink(destination: RecipeDetail(recipe: recipe)) {
Text(recipe.name)
}
}
}
.navigationViewStyle(.stack)
// Depois (iOS 16+)
NavigationStack {
List(recipes) { recipe in
NavigationLink(recipe.name, value: recipe)
}
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
}
De view-based NavigationLink para value-based
// Antes (obsoleto)
NavigationLink(destination: RecipeDetail(recipe: recipe)) {
Text(recipe.name)
}
// Depois
NavigationLink(recipe.name, value: recipe)
.navigationDestination(for: Recipe.self) { recipe in
RecipeDetail(recipe: recipe)
}
Notas Finais
- Sempre use NavigationStack sobre NavigationView em iOS 16+
- Prefira tipos de valor (Hashable/Codable) para navegação programática
- Coloque navigationDestination fora de containers lentos (LazyVGrid, List com seções)
- Isole estado de navegação com @MainActor para segurança com concorrência
- Cada aba deve ter seu próprio estado de navegação
- Trate erros de decodificação de NavigationPath graciosamente — nunca force unwrap
- Para apps iOS 18+, considere .sidebarAdaptable para layout adaptável
- Escolha a complexidade certa: Router para fluxos complexos, NavigationPath direto para casos simples