Depuração SwiftUI
Visão Geral
A depuração SwiftUI se enquadra em três categorias, cada uma com uma abordagem diagnóstica diferente:
- Visualização Não Atualizando – Você alterou algo, mas a visualização não redesenhada. Árvore de decisão para identificar se é mutação de struct, identidade de binding perdida, recriação acidental da visualização ou padrão de observador ausente.
- Falhas na Pré-visualização – Sua pré-visualização não compila ou falha imediatamente. Árvore de decisão para distinguir entre dependências ausentes, falhas na inicialização de estado e corrupção de cache do Xcode.
- Problemas de Layout – Visualizações aparecendo em posições erradas, tamanhos errados, sobrepondo-se inesperadamente. Padrões de referência rápida para cenários comuns.
Princípio central: Comece com sintomas observáveis, teste sistematicamente, elimine as causas uma a uma. Não adivinhe.
Requer: Xcode 26+, iOS 17+ (padrões iOS 14-16 ainda válidos, veja notas)
Skills relacionadas: axiom-xcode-debugging (diagnóstico de corrupção de cache), axiom-swift-concurrency (padrões de observador), axiom-swiftui-performance (perfilamento com Instruments), axiom-swiftui-layout (padrões de layout adaptativo)
Exemplos de Prompts
Estas são perguntas reais que desenvolvedores fazem e que esta skill foi projetada para responder:
1. "O item da minha lista não atualiza quando toco no botão de favorito, mesmo com os dados alterados"
→ A skill percorre a árvore de decisão para identificar mutação de struct vs binding perdido vs observador ausente
2. "A pré-visualização trava com 'Cannot find AppModel in scope' mas compila normalmente"
→ A skill mostra como fornecer dependências ausentes com .environment() ou .environmentObject()
3. "Meu contador reseta para 0 toda vez que alterno um booleano, por quê?"
→ A skill identifica a recriação acidental da visualização a partir de condicionais e mostra a correção com .opacity()
4. "Estou usando @Observable mas a visualização ainda não atualiza quando altero a propriedade"
→ A skill explica quando usar @State vs propriedades simples com objetos @Observable
5. "O campo de texto perde o foco quando começo a digitar, muito frustrante"
→ A skill identifica problemas de identidade no ForEach e mostra como usar IDs estáveis
Quando Usar a Depuração SwiftUI
Use esta skill quando
- ✅ Uma visualização não está atualizando quando você espera
- ✅ A pré-visualização falha ou não carrega
- ✅ O layout parece errado em dispositivos específicos
- ✅ Você está tentado a usar @ObservedObject como curativo em todo lugar
Use axiom-xcode-debugging em vez disso quando
- O aplicativo falha em tempo de execução (não na pré-visualização)
- A compilação falha completamente
- Você precisa de diagnóstico de ambiente
Use axiom-swift-concurrency em vez disso quando
- Perguntas sobre async/await ou MainActor
- Avisos de race condition de dados
Ferramentas de Depuração
Self._printChanges()
O SwiftUI fornece um método exclusivo de depuração para entender por que o body de uma visualização foi chamado.
Uso no LLDB:
// Defina um breakpoint no body da visualização
// No console LLDB:
(lldb) expression Self._printChanges()
Temporário no código (remova antes de enviar):
var body: some View {
let _ = Self._printChanges() // Apenas depuração
Text("Olá")
}
Interpretação da saída:
MyView: @self changed
- Significa que o valor da própria visualização mudou (parâmetros passados para a visualização)
MyView: count changed
- Significa que a propriedade @State "count" acionou a atualização
MyView: (nenhuma saída)
- Body não está sendo chamado; a visualização não está atualizando
⚠️ Importante:
- Prefixado com sublinhado → Pode ser removido em versões futuras
- NUNCA envie para a App Store com chamadas _printChanges
- Impacto no desempenho → Use apenas durante a depuração
Quando usar:
- Precisar entender o gatilho exato para a atualização da visualização
- Investigar atualizações inesperadas
- Verificar dependências após refatoração
Referência cruzada: Para padrões de atualização complexos, use o Instrumento SwiftUI → consulte a skill axiom-swiftui-performance
Árvore de Decisão: Visualização Não Atualizando
A frustração mais comum: você alterou @State mas a visualização não redesenhada. A causa raiz é sempre uma de quatro coisas.
Passo 1: Você Consegue Reproduzir em uma Pré-visualização Mínima?
#Preview {
SuaView()
}
SIM → O problema está no seu código. Continue para o Passo 2.
NÃO → Provavelmente é estado do Xcode ou corrupção de cache. Pule para a seção Falhas na Pré-visualização.
Passo 2: Diagnosticar a Causa Raiz
Causa Raiz 1: Mutação de Struct
Sintoma: Você modifica um valor @State diretamente, mas a visualização não atualiza.
Por que acontece: O SwiftUI não vê mutações diretas em structs. Você precisa reatribuir o valor inteiro.
// ❌ ERRADO: Mutação direta não aciona atualização
@State var items: [String] = []
func addItem(_ item: String) {
items.append(item) // SwiftUI não vê essa alteração
}
// ✅ CERTO: Reatribuição aciona atualização
@State var items: [String] = []
func addItem(_ item: String) {
var newItems = items
newItems.append(item)
self.items = newItems // Reatribuição completa
}
// ✅ TAMBÉM CERTO: Use um binding
@State var items: [String] = []
var itemsBinding: Binding<[String]> {
Binding(
get: { items },
set: { items = $0 }
)
}
Corrija: Sempre reatribua o valor inteiro da struct, não partes dela.
Causa Raiz 2: Identidade de Binding Perdida
Sintoma: Você passa um binding para uma visualização filha, mas alterações na filha não atualizam a pai.
Por que acontece: Você está passando .constant() ou criando um novo binding a cada vez, quebrando a conexão bidirecional.
// ❌ ERRADO: Binding constante é somente leitura
@State var isOn = false
ToggleFilho(value: .constant(isOn)) // Alterações ignoradas
// ❌ ERRADO: Novo binding criado a cada renderização
@State var nome = ""
TextField("Nome", text: Binding(
get: { nome },
set: { nome = $0 }
)) // Novo objeto binding a cada renderização da pai
// ✅ CERTO: Passe o binding real
@State var isOn = false
ToggleFilho(value: $isOn)
// ✅ CERTO (iOS 17+): Use @Bindable para objetos @Observable
@Observable class Livro {
var titulo = "Exemplo"
var disponivel = true
}
struct EditarView: View {
@Bindable var livro: Livro // Habilita $livro.titulo
var body: some View {
TextField("Título", text: $livro.titulo)
Toggle("Disponível", isOn: $livro.disponivel)
}
}
// ✅ TAMBÉM CERTO (iOS 17+): @Bindable como variável local
struct ListaView: View {
@State private var livros = [Livro(), Livro()]
var body: some View {
List(livros) { livro in
@Bindable var livro = livro // Binding inline
TextField("Título", text: $livro.titulo)
}
}
}
// ✅ CERTO (pré-iOS 17): Crie binding uma vez, não no body
@State var nome = ""
@State var nomeBinding: Binding<String>?
var body: some View {
if nomeBinding == nil {
nomeBinding = Binding(
get: { nome },
set: { nome = $0 }
)
}
return TextField("Nome", text: nomeBinding!)
}
Corrija: Passe $state diretamente quando possível. Para objetos @Observable (iOS 17+), use @Bindable. Se estiver criando bindings personalizados (pré-iOS 17), crie-os no init ou cacheie-os, não no body.
Causa Raiz 3: Recriação Acidental da Visualização
Sintoma: A visualização atualiza, mas os valores @State resetam para o estado inicial. Você vê breves flashes de valores iniciais.
Por que acontece: A visualização recebeu uma nova identidade (removida de um condicional, movida em um contêiner, ou o próprio contêiner foi recriado), fazendo com que o SwiftUI a trate como uma nova visualização.
// ❌ ERRADO: Identidade da visualização muda quando a condição alterna
@State var contagem = 0
var body: some View {
VStack {
if mostrarContador {
Contador() // Ganha nova identidade cada vez que mostrarContador muda
}
Botao("Alternar") {
mostrarContador.toggle()
}
}
}
// Contador é recriado, @State contagem reseta para 0
// ✅ CERTO: Preserve identidade com opacidade ou hidden
@State var contagem = 0
var body: some View {
VStack {
Contador()
.opacity(mostrarContador ? 1 : 0)
Botao("Alternar") {
mostrarContador.toggle()
}
}
}
// ✅ TAMBÉM CERTO: Use id() se precisar mostrar condicionalmente
@State var contagem = 0
var body: some View {
VStack {
if mostrarContador {
Contador()
.id("contador") // Identidade estável
}
Botao("Alternar") {
mostrarContador.toggle()
}
}
}
Corrija: Preserve a identidade da visualização usando .opacity() em vez de condicionais, ou aplique .id() com um identificador estável.
Causa Raiz 4: Padrão de Observador Ausente
Sintoma: Um objeto mudou, mas as visualizações que o observam não atualizaram.
Por que acontece: O SwiftUI não sabe que deve observar as alterações no objeto.
// ❌ ERRADO: Alterações de propriedade não acionam atualização
class Modelo {
var contagem = 0 // Não observável
}
struct ConteudoView: View {
let model = Modelo() // Nova instância a cada renderização, não observável
var body: some View {
Text("\(model.contagem)")
Botao("Incrementar") {
model.contagem += 1 // Visualização não atualiza
}
}
}
// ✅ CERTO (iOS 17+): Use @Observable com @State
@Observable class Modelo {
var contagem = 0 // Sem necessidade de @Published
}
struct ConteudoView: View {
@State private var model = Modelo() // @State, não @StateObject
var body: some View {
Text("\(model.contagem)")
Botao("Incrementar") {
model.contagem += 1 // Visualização atualiza
}
}
}
// ✅ CERTO (iOS 17+): Objetos @Observable injetados
struct ConteudoView: View {
var model: Modelo // Apenas uma propriedade simples
var body: some View {
Text("\(model.contagem)") // Visualização atualiza quando contagem muda
}
}
// ✅ CERTO (iOS 17+): @Observable com environment
@Observable class AppModel {
var contagem = 0
}
@main
struct MeuApp: App {
@State private var model = AppModel()
var body: some Scene {
WindowGroup {
ConteudoView()
.environment(model) // Adicionar ao environment
}
}
}
struct ConteudoView: View {
@Environment(AppModel.self) private var model // Ler do environment
var body: some View {
Text("\(model.contagem)")
}
}
// ✅ CERTO (pré-iOS 17): Use @StateObject/ObservableObject
class Modelo: ObservableObject {
@Published var contagem = 0
}
struct ConteudoView: View {
@StateObject var model = Modelo() // Para instâncias próprias
var body: some View {
Text("\(model.contagem)")
Botao("Incrementar") {
model.contagem += 1 // Visualização atualiza
}
}
}
// ✅ CERTO (pré-iOS 17): Use @ObservedObject para instâncias injetadas
struct ConteudoView: View {
@ObservedObject var model: Modelo // Passado da pai
var body: some View {
Text("\(model.contagem)")
}
}
Corrija (iOS 17+): Use a macro @Observable na sua classe e @State para armazená-la. As visualizações rastreiam automaticamente as dependências das propriedades que leem.
Corrija (pré-iOS 17): Use @StateObject se você possui o objeto, @ObservedObject se for injetado, ou @EnvironmentObject se for compartilhado pela árvore.
Por que @Observable é melhor (iOS 17+):
- Rastreamento automático de dependências (apenas leituras acionam atualizações)
- Sem necessidade de wrapper
@Published - Funciona com
@Stateem vez de@StateObject - Pode ser passado como propriedade simples em vez de
@ObservedObject
Veja também: Gerenciando dados de modelo no seu aplicativo
Resumo da Árvore de Decisão
digraph view_not_updating {
start [label="Visualização não está atualizando?" shape=diamond];
reproduce [label="Consegue reproduzir na pré-visualização?" shape=diamond];
cause [label="O que mudou?" shape=diamond];
start -> reproduce;
reproduce -> cause [label="sim: bug no código"];
reproduce -> "Cache/Estado Xcode → Falhas na Pré-visualização" [label="não"];
cause -> "Mutação de Struct" [label="modificou struct diretamente"];
cause -> "Identidade de Binding Perdida" [label="passou binding para filha"];
cause -> "Recriação Acidental" [label="visualização dentro de condicional"];
cause -> "Observador Ausente" [label="objeto mudou, visualização não"];
}
Árvore de Decisão: Falhas na Pré-visualização
Quando sua pré-visualização não carrega ou falha imediatamente, as três causas raiz são distintas.
Passo 1: Qual é o Erro?
Tipo de Erro 1: "Cannot find in scope" ou "No such module"
Causa raiz: A pré-visualização está faltando uma dependência necessária (@EnvironmentObject, @Environment, módulo importado).
// ❌ ERRADO: ConteudoView precisa de um modelo, a pré-visualização não o fornece
struct ConteudoView: View {
@EnvironmentObject var model: AppModel
var body: some View {
Text(model.titulo)
}
}
#Preview {
ConteudoView() // Falha: modelo não encontrado
}
// ✅ CERTO: Forneça a dependência
#Preview {
ConteudoView()
.environmentObject(AppModel())
}
// ✅ TAMBÉM CERTO: Verifique importações faltando
// Se usar tipos personalizados, certifique-se de que estão importados no arquivo de pré-visualização
#Preview {
MinhaViewPersonalizada() // Certifique-se de que MinhaViewPersonalizada está definida ou importada
}
Corrija: Rastreie o erro, descubra o que está faltando e forneça à pré-visualização.
Tipo de Erro 2: Erro fatal ou falha silenciosa (sem mensagem de erro)
Causa raiz: A inicialização do estado falhou em tempo de execução. A visualização tentou acessar dados que não existem.
// ❌ ERRADO: Índice fora dos limites em tempo de execução
struct ListaView: View {
@State var indiceSelecionado = 10
let items = ["a", "b", "c"]
var body: some View {
Text(items[indiceSelecionado]) // Falha: índice 10 não existe
}
}
// ❌ ERRADO: Desempacotamento forçado de opcional falha
struct DetalheView: View {
@State var dados: Dados?
var body: some View {
Text(dados!.titulo) // Falha se dados for nil
}
}
// ✅ CERTO: Valores padrão seguros
struct ListaView: View {
@State var indiceSelecionado = 0 // Índice válido
let items = ["a", "b", "c"]
var body: some View {
if indiceSelecionado < items.count {
Text(items[indiceSelecionado])
}
}
}
// ✅ CERTO: Lidando com opcionais
struct DetalheView: View {
@State var dados: Dados?
var body: some View {
if let dados = dados {
Text(dados.titulo)
} else {
Text("Sem dados")
}
}
}
Corrija: Verifique valores iniciais para @State. Forneça dados de pré-visualização realistas. Use valores padrão seguros em vez de forçar desempacotamento. Inicialize bindings e StateObject corretamente.
Passo 2: Testes Rápidos
Se você não tem certeza se é o código ou o cache:
- Limpar pasta de Derived Data: Produto → Limpar Pasta de Derived Data no Xcode
- Recarregar exibição ao vivo no Simulator: Produto → Recarregar Exibição ao Live no Simulator
- Testar em um arquivo vazio: Crie um novo arquivo swift, cole a visualização, execute a pré-visualização
- Testar sem dependências: Se a visualização receber muitos objetos, teste com uma versão simplificada
- Verificar esquema: Certifique-se de que o arquivo de pré-visualização está no alvo de compilação correto
Corrigindo cache: Se o cache estiver corrompido, use a skill axiom-xcode-debugging para diagnóstico completo. Solução comum: Editar o esquema → Executar → Opções → "Limpar o log e reiniciar" (funciona melhor do que limpeza manual).
Resumo da Árvore de Decisão
digraph preview_crashes {
start [label="Pré-visualização falha?" shape=diamond];
type [label="Tipo de erro?" shape=diamond];
start -> type;
type -> "Cannot find in scope" [label="mensagem de erro"];
type -> "Falha silenciosa / Erro fatal" [label="sem mensagem"];
"Cannot find in scope" -> "Fornecer dependência";
"Falha silenciosa / Erro fatal" -> "Verificar inicialização de estado";
"Fornecer dependência" -> "Testar pré-visualização" [label="adicionou dependência"];
"Verificar inicialização de estado" -> "Testar pré-visualização" [label="corrigiu inicialização"];
"Testar pré-visualização" -> "Limpar Derived Data" [label="ainda falha"];
"Limpar Derived Data" -> "Recarregar Exibição ao Vivo" [label="não funciona?"];
"Recarregar Exibição ao Vivo" -> "Testar em arquivo vazio" [label="ainda falha"];
"Testar em arquivo vazio" -> "Usar axiom-xcode-debugging" [label="ainda falha"];
}
Problemas de Layout
Layouts errados geralmente têm três causas: contêiner errado, espaçamento/size class ou modificadores de alinhamento perdidos.
Diagnóstico Rápido de Layout
Verifique essas primeiras
- O contêiner certo? – HStack vs VStack, ZStack para sobreposições. ScrollView para conteúdo rolável. List vs VStack.
- Incompatibilidade de tamanho? – Tudo que é automático? Verifique frame(minWidth:idealWidth:maxWidth:).
- Alinhamento? – Padrões alinhados ao centro. Esquerda:
.frame(maxWidth: .infinity, alignment: .leading). Em grades: alinhamentos por coluna. - Sobreposição? – Views sobrepostas? ZStack com alinhamento.
.offset()movendo de lugar. - Diferentes tamanhos de dispositivo? – Teste no iPad vs iPhone. Size classes mudam layout.
- Esqueceram de ligar o editor de pré-visualização? – Sim, acontece com frequência.
Referência Rápida
Recuo de linha:
VStack(alignment: .leading, spacing: 8) {
Text("Linha 1")
Text("Este texto fica recuado")
.padding(.leading, 16)
}
Distribution e spacing:
HStack {
Text("Esquerda")
Spacer() // Empurra para a direita
Text("Direita")
}
Grade de largura total:
LazyVGrid(columns: [
GridItem(.flexible()),
GridItem(.flexible()),
GridItem(.flexible()),
], spacing: 16) {
// Views de largura igual
}
Acessórios centralizados:
VStack {
// Empurra para baixo
Spacer()
Text("Centralizado verticalmente")
// Funciona porque VStack centraliza com Spacer()
}
Quando Ignorar Problemas de Layout
Você pode gastar horas ajustando pixels. Ignore se:
- Funciona em dispositivos reais (o simulador muitas vezes está errado)
- Um refinamento não é crítico para a usabilidade
- A Apple mudou o comportamento de layout em uma versão beta
- Você pode consertar rapidamente depois com um dispositivo real
Princípio: Layouts perfeitos são bons para portfólios. Layouts funcionais entregam produtos.
Solução Rápida #1: Mutação de Struct (Mais Comum)
Se você está frustrado e quer apenas que funcione:
// ✅ MUDE PARA ISSO: Reatribuição completa
@State var items: [String] = []
func addItem(_ item: String) {
var newItems = items
newItems.append(item)
items = newItems // Linha mágica
}
// Ou ainda mais rápido:
func addItem(_ item: String) {
items = items + [item]
}
Lembrete: Structs são tipos valor. Você deve copiar, modificar e reatribuir. Ou use ObservableObject com classe.
Solução Rápida #2: Identidade de Binding Perdida (Segundo Mais Comum)
// ✅ Troque '.constant' por '$'
// ❌ ToggleFilho(value: .constant(isOn))
// ✅ ToggleFilho(value: $isOn)
// Para objetos (iOS 17+):
@Bindable var livro: Livro // Em vez de `let livro: Livro`
Lembrete: Bindings são pontes. .constant() é uma rua de mão única. $state é mão dupla.
Solução Rápida #3: Recriação Acidental da Visualização
// ✅ Troque condicionais por opacidade
if mostrarView {
MinhaView() // Sendo recriada
}
// ✅ MUDE PARA:
MinhaView()
.opacity(mostrarView ? 1 : 0)
Lembrete: Muitas visualizações são idênticas, exceto onde estão. Mantenha a identidade.
Hacks Rápidos (Para quando você não consegue dormir)
Não consegue encontrar o bug?
- Inspecione visualmente a visualização em tempo de execução: clique em Depurador → Mostrar Hierarquia de Visualização
- Adicione borda vermelha:
.border(Color.red)em cada visualização para ver limites - Verifique se a pré-visualização está em execução (sério, verifique a barra de status)
Ainda não consegue encontrar?
- Durma (o tipo com zzz, não o enum)
- Volte amanhã e execute a pré-visualização
- Funciona? Sim. Você foi desmascarado pelo
_printChangese não quer admitir. - Esta skill é inspirada em horas reais perdidas em mutações de struct.
Você consegue. Apenas não seja um struct.
Notas de Versão
iOS 17+ / Xcode 15+
@Observablemacro simplifica drasticamente o rastreamento de dependências@Bindablepermite bindings em objetos @Observable@Environmentagora funciona com tipos @Observable (não apenas ObservableObject)- Pré-visualizações agora suportam macros e são mais rápidas
iOS 14-16 / Xcode 12-14
- Use
@StateObjectem vez de@State+ @Observable - Use
@ObservedObjectpara objetos injetados - Use
@Publishedpara marcadores de observação - Pré-visualizações podem precisar de alvos de compilação explícitos no arquivo de pré-visualização
Para Ambas as Versões
Self._printChanges()funciona da mesma forma- Árvores de decisão e estratégia de depuração são idênticas
- Apenas a sintaxe para observação de propriedades muda