Diagnóstico de Navegação SwiftUI
Visão Geral
Princípio central 85% dos problemas de navegação vêm de erros no gerenciamento de estado do caminho, problemas de identidade de views ou erros de posicionamento — não de defeitos do SwiftUI.
O sistema de navegação do SwiftUI é usado por milhões de aplicativos e lida com padrões de navegação complexos de forma confiável. Se sua navegação está falhando, sem resposta ou se comportando inesperadamente, o problema é quase sempre em como você está gerenciando o estado da navegação, não no framework em si.
Esta habilidade fornece diagnósticos sistemáticos para identificar causas raiz em minutos, não em horas.
Bandeiras Vermelhas — Suspeite de Problema de Navegação
Se você vir QUALQUER um destes, suspeite de um problema de código, não de uma quebra do framework:
-
Tocar na navegação não faz nada (link presente, mas não empurra)
-
Botão voltar leva para a tela errada ou para a raiz
-
Deep link abre o aplicativo, mas mostra a tela errada
-
Estado de navegação perdido ao trocar de abas
-
Estado de navegação perdido quando o aplicativo vai para background
-
Mesmo NavigationLink empurra duas vezes
-
Animação de navegação travada ou irregular
-
Crash com
navigationDestinationno stack trace -
❌ PROIBIDO "A navegação do SwiftUI está quebrada, vamos usar UINavigationController"
- NavigationStack é usado pelos próprios aplicativos da Apple
- Usar UIKit adiciona complexidade e perde os benefícios do gerenciamento de estado do SwiftUI
- A interoperabilidade com UIKit tem seus próprios casos extremos que você levará semanas descobrindo
- Seu problema é quase certamente gerenciamento de caminho, não um defeito do framework
Distinção crítica O comportamento do NavigationStack é determinístico. Se não está funcionando, você está modificando o estado incorretamente, tem problemas de identidade de view ou o navigationDestination está mal posicionado.
Primeiros Passos Obrigatórios
SEMPRE execute estas verificações PRIMEIRO (antes de alterar o código):
// 1. Adicione logging do NavigationPath
NavigationStack(path: $path) {
RootView()
.onChange(of: path.count) { oldCount, newCount in
print("📍 Caminho alterado: \(oldCount) → \(newCount)")
// Se isso nunca disparar, o link não está modificando o caminho
// Se disparar inesperadamente, outra coisa está modificando o caminho
}
}
// 2. Verifique se navigationDestination está visível
// Coloque um print temporário no closure do destino
.navigationDestination(for: Recipe.self) { recipe in
let _ = print("🔗 Destino para Recipe: \(recipe.name)")
RecipeDetail(recipe: recipe)
}
// Se isso nunca imprimir, o destino não está sendo avaliado
// 3. Verifique se NavigationLink está dentro de NavigationStack
// Inspeção visual: Rastreie de NavigationLink para cima na hierarquia de views
// Deve encontrar NavigationStack, não outro contêiner primeiro
// 4. Verifique a localização do estado do caminho
// @State deve estar em uma view estável (não recriada a cada renderização)
// Deve ser @State, @StateObject ou @Observable — não uma variável local
// 5. Teste o caso básico isoladamente
// Crie uma reprodução mínima
NavigationStack {
NavigationLink("Teste", value: "teste")
.navigationDestination(for: String.self) { str in
Text("Empurrado: \(str)")
}
}
// Se isso funcionar, o problema está na sua configuração específica
O que isso lhe diz
| Observação | Diagnóstico | Próximo Passo |
|---|---|---|
| onChange nunca dispara ao tocar | NavigationLink não está na hierarquia NavigationStack | Padrão 1a |
| onChange dispara, mas view não é empurrada | navigationDestination não encontrado/carregado | Padrão 1b |
| onChange dispara, view empurra, depois pop imediato | Problema de identidade de view ou modificação de caminho | Padrão 2a |
| Caminho muda inesperadamente (não do toque) | Código externo modificando o caminho | Padrão 2b |
| Deep link path.append() não navega | Problema de timing ou thread errada | Padrão 3b |
| Estado perdido ao trocar de aba | NavigationStack compartilhado entre abas | Padrão 4a |
| Funciona na primeira vez, falha ao retornar | Problema de recriação de view | Padrão 5a |
INTERPRETAÇÃO OBRIGATÓRIA
Antes de alterar QUALQUER código, identifique UM destes:
- Se tocar no link não faz nada E nenhum onChange → Link fora do NavigationStack (verifique a hierarquia)
- Se onChange dispara, mas nada empurra → navigationDestination fora do escopo (verifique o posicionamento)
- Se empurra e depois volta imediatamente → Mudança de identidade de view ou reinicialização do caminho (verifique a localização do @State)
- Se deep link falha → Problema de timing ou MainActor (verifique a thread)
- Se crash → Force unwrap na decodificação do caminho ou registro de tipo ausente
Se os diagnósticos forem contraditórios ou pouco claros
- PARE. Não prossiga para os padrões ainda
- Adicione prints em todos os pontos de modificação do caminho
- Crie um caso de reprodução mínimo
- Teste primeiro com valores do tipo String (caso mais simples)
Árvore de Decisão
Use isto para chegar ao padrão de diagnóstico correto em 2 minutos:
Problema de navegação?
├─ Tocar na navegação não faz nada?
│ ├─ NavigationLink dentro do NavigationStack?
│ │ ├─ Não → Padrão 1a (Link fora do Stack)
│ │ └─ Sim → Verifique navigationDestination
│ │
│ ├─ navigationDestination registrado?
│ │ ├─ Dentro de contêiner lazy? → Padrão 1b (Carregamento Lento)
│ │ ├─ Tipo incompatível? → Padrão 1c (Registro de Tipo)
│ │ └─ Bloqueado por sheet/popover? → Padrão 1d (Bloqueio Modal)
│ │
│ └─ Usando link baseado em view?
│ └─ → Padrão 1e (API Obsoleta)
│
├─ Pop inesperado ao voltar?
│ ├─ Pop imediato após empurrar?
│ │ ├─ View body recriando caminho? → Padrão 2a (Recriação de Caminho)
│ │ ├─ @State na view errada? → Padrão 2a (Localização do Estado)
│ │ └─ ForEach id mudando? → Padrão 2c (Mudança de Identidade)
│ │
│ ├─ Pop quando não deveria?
│ │ ├─ Código externo chamando removeLast? → Padrão 2b (Modificação Inesperada)
│ │ ├─ Task cancelada? → Padrão 2b (Cancelamento Assíncrono)
│ │ └─ Problema com MainActor? → Padrão 2d (Threading)
│ │
│ └─ Comportamento do botão voltar errado?
│ └─ → Padrão 2e (Corrupção do Stack)
│
├─ Deep link não funcionando?
│ ├─ URL não recebida?
│ │ ├─ onOpenURL não chamado? → Verifique esquema de URL no Info.plist
│ │ └─ Problema com Universal Links? → Verifique apple-app-site-association
│ │
│ ├─ URL recebida, caminho não atualizado?
│ │ ├─ path.append não está no MainActor? → Padrão 3a (Threading)
│ │ ├─ Problema de timing (app não pronto)? → Padrão 3b (Inicialização)
│ │ └─ NavigationStack ainda não criado? → Padrão 3b (Ciclo de Vida)
│ │
│ └─ Caminho atualizado, tela errada mostrada?
│ ├─ Ordem do caminho errada? → Padrão 3c (Construção do Caminho)
│ ├─ Tipo errado anexado? → Padrão 3c (Tipo Incompatível)
│ └─ Item não encontrado? → Padrão 3d (Resolução de Dados)
│
├─ Estado perdido?
│ ├─ Perdido ao trocar de aba?
│ │ ├─ NavigationStack compartilhado? → Padrão 4a (Estado Compartilhado)
│ │ └─ Recriação de aba? → Padrão 4a (Identidade de Aba)
│ │
│ ├─ Perdido ao ir para background/foreground?
│ │ ├─ Sem SceneStorage? → Padrão 4b (Sem Persistência)
│ │ └─ Falha na decodificação? → Padrão 4c (Erro de Decodificação)
│ │
│ └─ Perdido na rotação/mudança de tamanho?
│ └─ → Padrão 4d (Recriação de Layout)
│
├─ Problema com NavigationSplitView?
│ ├─ Sidebar não visível no iPad?
│ │ ├─ columnVisibility não definido? → Padrão 6a (Visibilidade da Coluna)
│ │ └─ Compact size class? → Padrão 6a (Adaptação Automática)
│ │
│ ├─ Detail mostra tela em branco no iPad?
│ │ ├─ Nenhuma view de detalhe padrão? → Padrão 6b (Detalhe Ausente)
│ │ └─ Selection binding nulo? → Padrão 6b (Estado da Seleção)
│ │
│ └─ Funciona no iPhone, quebrado no iPad?
│ └─ → Padrão 6c (Adaptação de Plataforma)
│
└─ Crash?
├─ EXC_BAD_ACCESS no código de navegação?
│ └─ → Padrão 5a (Problema de Memória)
│
├─ Erro fatal: tipo não registrado?
│ └─ → Padrão 5b (Destino Ausente)
│
└─ Falha na decodificação ao restaurar?
└─ → Padrão 5c (Crash na Restauração)
Regras de Seleção de Padrões (OBRIGATÓRIO)
Antes de prosseguir para um padrão:
- Tocar na navegação não faz nada → Adicione logging onChange PRIMEIRO, depois Padrão 1
- Pop inesperado → Descubra O QUE está modificando o caminho (logging), depois Padrão 2
- Falha de deep link → Verifique se a URL foi recebida (print em onOpenURL), depois Padrão 3
- Estado perdido → Identifique QUANDO foi perdido (troca de aba vs background), depois Padrão 4
- Crash → Obtenha o stack trace completo, depois Padrão 5
Aplique UM padrão de cada vez
- Implemente a correção de um padrão
- Teste completamente
- Só se o problema persistir, tente o próximo padrão
- NÃO aplique múltiplos padrões simultaneamente (não é possível isolar a causa)
PROIBIDO
- Adivinhar soluções sem diagnóstico
- Mudar várias coisas ao mesmo tempo
- Usar UINavigationController "porque o SwiftUI está quebrado"
- Adicionar atrasos/DispatchQueue.main.async sem entender o porquê
- Mudar para NavigationLink baseado em view "para evitar problemas de caminho"
Padrões de Diagnóstico
Padrão 1a: NavigationLink Fora do NavigationStack
Custo de tempo 5-10 minutos
Sintoma
- Tocar em NavigationLink não faz nada
- Nenhuma navegação ocorre, nenhum erro
- onChange(of: path) nunca dispara
Diagnóstico
// Verifique a hierarquia de views — NavigationLink deve estar DENTRO do NavigationStack
// ❌ ERRADO — Link fora do stack
struct ContentView: View {
var body: some View {
VStack {
NavigationLink("Ir", value: "teste") // Fora do stack!
NavigationStack {
Text("Raiz")
}
}
}
}
// Verifique: Adicione cor de fundo ao NavigationStack
NavigationStack {
Color.red // Se o link estiver sobre o vermelho, está dentro
}
Correção
// ✅ CORRETO — Link dentro do stack
struct ContentView: View {
var body: some View {
NavigationStack {
VStack {
NavigationLink("Ir", value: "teste") // Dentro do stack
Text("Raiz")
}
.navigationDestination(for: String.self) { str in
Text("Empurrado: \(str)")
}
}
}
}
Verificação
- Toque no link, a navegação ocorre
- onChange(of: path) dispara ao tocar
Padrão 1b: navigationDestination em Contêiner Lazy
Custo de tempo 10-15 minutos
Sintoma
- Tocar no NavigationLink não faz nada OU funciona intermitentemente
- onChange dispara (caminho atualizado), mas a view não é empurrada
- O console pode mostrar: "A navigationDestination for [Type] was not found"
Diagnóstico
// ❌ ERRADO — Destino dentro de contêiner lazy (pode não ser carregado)
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // Pode não ser avaliado!
}
}
}
}
Correção
// ✅ CORRETO — Destino fora do contêiner lazy
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // Sempre disponível
}
Verificação
- Adicione print no closure do destino — deve sempre imprimir na navegação
- Funciona independentemente da posição de scroll
Padrão 1c: Incompatibilidade no Registro de Tipo
Custo de tempo 10 minutos
Sintoma
- Tocar na navegação não faz nada
- Nenhum navigationDestination correspondente para o tipo do valor
- Pode funcionar para alguns links, mas não para outros
Diagnóstico
// Verifique: O tipo do valor deve CORRESPONDER EXATAMENTE ao tipo do destino
// Link usa Recipe
NavigationLink(recipe.name, value: recipe) // value é Recipe
// Destino registrado para... Recipe.ID?
.navigationDestination(for: Recipe.ID.self) { id in // ❌ Tipo errado!
RecipeDetail(id: id)
}
Correção
// Corresponda os tipos exatamente
NavigationLink(recipe.name, value: recipe) // Recipe
.navigationDestination(for: Recipe.self) { recipe in // ✅ Recipe
RecipeDetail(recipe: recipe)
}
// OU altere o link para usar ID
NavigationLink(recipe.name, value: recipe.id) // Recipe.ID
.navigationDestination(for: Recipe.ID.self) { id in // ✅ Recipe.ID
RecipeDetail(id: id)
}
Verificação
- Imprima o tipo no destino:
print(type(of: value)) - Os tipos devem corresponder exatamente (sem herança)
Padrão 2a: NavigationPath Recriado a Cada Renderização
Custo de tempo 15-20 minutos
Sintoma
- A navegação empurra e depois volta imediatamente
- Parece "piscar" a view de destino
- Funciona uma vez, depois falha, ou falha imediatamente
Diagnóstico
// ❌ ERRADO — Caminho criado no corpo da view (reinicializado a cada renderização)
struct ContentView: View {
var body: some View {
let path = NavigationPath() // Recriado toda vez!
NavigationStack(path: .constant(path)) {
// ...
}
}
}
// ❌ ERRADO — @State em view filha que é recriada
struct ParentView: View {
@State var showChild = true
var body: some View {
if showChild {
ChildView() // Recriada quando showChild alterna
}
}
}
struct ChildView: View {
@State var path = NavigationPath() // Perdido quando ChildView é recriada
// ...
}
Correção
// ✅ CORRETO — @State em nível estável
struct ContentView: View {
@State private var path = NavigationPath() // Persiste entre renderizações
var body: some View {
NavigationStack(path: $path) {
RootView()
}
}
}
// ✅ CORRETO — @StateObject para ObservableObject
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
var body: some View {
NavigationStack(path: $navModel.path) {
RootView()
}
}
}
Verificação
- Adicione logging onChange — o caminho não deve reinicializar inesperadamente
- Navegue, espere, path.count permanece estável
Padrão 2d: Caminho Modificado Fora do MainActor
Custo de tempo 10-15 minutos
Sintoma
- A navegação funciona algumas vezes, falha em outras
- Avisos do Swift 6 sobre isolamento MainActor
- Pops inesperados ou corrupção de estado
Diagnóstico
// ❌ ERRADO — Modificando o caminho de uma tarefa em background
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ⚠️ Não está no MainActor!
}
// Verifique: Pesquise por path.append, path.removeLast fora do contexto @MainActor
Correção
// ✅ CORRETO — Garanta MainActor
@MainActor
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ✅ Isolado no MainActor
}
// OU despache explicitamente
func loadAndNavigate() async {
let recipe = await fetchRecipe()
await MainActor.run {
path.append(recipe)
}
}
// ✅ MELHOR — Use @Observable com @
…
[truncado para tradução]