Depuración en SwiftUI
Resumen
La depuración en SwiftUI se divide en tres categorías, cada una con un enfoque de diagnóstico diferente:
- La vista no se actualiza – Cambiaste algo pero la vista no se redibujó. Árbol de decisión para identificar si es mutación de struct, pérdida de identidad de binding, recreación accidental de vista o falta de patrón observador.
- Fallos en la previsualización – Tu previsualización no compila o falla inmediatamente. Árbol de decisión para distinguir entre dependencias faltantes, fallos en la inicialización del estado y corrupción de la caché de Xcode.
- Problemas de diseño – Las vistas aparecen en posiciones incorrectas, con tamaños incorrectos o superpuestas inesperadamente. Patrones de referencia rápida para escenarios comunes.
Principio fundamental: Comienza con los síntomas observables, prueba de forma sistemática, elimina las causas una por una. No adivines.
Requiere: Xcode 26+, iOS 17+ (los patrones de iOS 14-16 siguen siendo válidos, consulta las notas)
Skills relacionados: axiom-xcode-debugging (diagnóstico de corrupción de caché), axiom-swift-concurrency (patrones de observación), axiom-swiftui-performance (perfilado con Instruments), axiom-swiftui-layout (patrones de diseño adaptativo)
Ejemplos de prompts
Estas son preguntas reales que los desarrolladores hacen y que este skill está diseñado para responder:
1. "El elemento de mi lista no se actualiza cuando toco el botón de favorito, aunque los datos cambiaron"
→ El skill recorre el árbol de decisión para identificar mutación de struct vs pérdida de binding vs observador faltante
2. "La previsualización falla con 'Cannot find AppModel in scope' pero compila bien"
→ El skill muestra cómo proporcionar las dependencias faltantes con .environment() o .environmentObject()
3. "Mi contador se reinicia a 0 cada vez que cambio un booleano, ¿por qué?"
→ El skill identifica la recreación accidental de vista por condicionales y muestra la solución con .opacity()
4. "Estoy usando @Observable pero la vista aún no se actualiza cuando cambio la propiedad"
→ El skill explica cuándo usar @State vs propiedades simples con objetos @Observable
5. "El campo de texto pierde el foco cuando empiezo a escribir, muy frustrante"
→ El skill identifica problemas de identidad en ForEach y muestra cómo usar IDs estables
Cuándo usar la depuración en SwiftUI
Usa este skill cuando
- ✅ Una vista no se está actualizando cuando esperas que lo haga
- ✅ La previsualización falla o no se carga
- ✅ El diseño se ve mal en dispositivos específicos
- ✅ Te sientes tentado a parchear con @ObservedObject por todas partes
Usa axiom-xcode-debugging en su lugar cuando
- La aplicación falla en tiempo de ejecución (no en la previsualización)
- La compilación falla por completo
- Necesitas diagnósticos del entorno
Usa axiom-swift-concurrency en su lugar cuando
- Hay preguntas sobre async/await o MainActor
- Hay advertencias de condiciones de carrera de datos
Herramientas de depuración
Self._printChanges()
SwiftUI proporciona un método solo de depuración para entender por qué se llamó al body de una vista.
Uso en LLDB:
// Establecer un punto de interrupción en el body de la vista
// En la consola de LLDB:
(lldb) expression Self._printChanges()
Temporal en código (eliminar antes de enviar):
var body: some View {
let _ = Self._printChanges() // Solo depuración
Text("Hola")
}
Interpretación de la salida:
MyView: @self changed
- Significa que el valor de la vista en sí mismo cambió (parámetros pasados a la vista)
MyView: count changed
- Significa que la propiedad @State "count" desencadenó la actualización
MyView: (sin salida)
- No se está llamando a body; la vista no se está actualizando en absoluto
⚠️ Importante:
- Prefijado con guión bajo → Puede eliminarse en versiones futuras
- NUNCA enviar a la App Store con llamadas a _printChanges
- Impacto en el rendimiento → Usar solo durante la depuración
Cuándo usarlo:
- Necesitas entender el desencadenante exacto de la actualización de la vista
- Investigando actualizaciones inesperadas
- Verificando dependencias después de refactorizar
Referencia cruzada: Para patrones de actualización complejos, usa el Instrumento de SwiftUI → consulta el skill axiom-swiftui-performance
Árbol de decisión: La vista no se actualiza
La frustración más común: cambiaste @State pero la vista no se redibujó. La causa raíz es siempre una de cuatro cosas.
Paso 1: ¿Puedes reproducirlo en una previsualización mínima?
#Preview {
YourView()
}
SÍ → El problema está en tu código. Continúa al Paso 2.
NO → Probablemente es un estado de Xcode o corrupción de caché. Salta a la sección Fallos en la previsualización.
Paso 2: Diagnosticar la causa raíz
Causa raíz 1: Mutación de struct
Síntoma: Modificas un valor @State directamente, pero la vista no se actualiza.
Por qué ocurre: SwiftUI no ve las mutaciones directas en los structs. Necesitas reasignar el valor completo.
// ❌ INCORRECTO: La mutación directa no desencadena la actualización
@State var items: [String] = []
func addItem(_ item: String) {
items.append(item) // SwiftUI no ve este cambio
}
// ✅ CORRECTO: La reasignación desencadena la actualización
@State var items: [String] = []
func addItem(_ item: String) {
var newItems = items
newItems.append(item)
self.items = newItems // Reasignación completa
}
// ✅ TAMBIÉN CORRECTO: Usa un binding
@State var items: [String] = []
var itemsBinding: Binding<[String]> {
Binding(
get: { items },
set: { items = $0 }
)
}
Arrglalo: Siempre reasigna el valor completo del struct, no partes de él.
Causa raíz 2: Pérdida de identidad del binding
Síntoma: Pasas un binding a una vista hija, pero los cambios en la hija no actualizan la vista padre.
Por qué ocurre: Estás pasando .constant() o creando un nuevo binding cada vez, rompiendo la conexión bidireccional.
// ❌ INCORRECTO: El binding constante es de solo lectura
@State var isOn = false
ToggleChild(value: .constant(isOn)) // Los cambios se ignoran
// ❌ INCORRECTO: Nuevo binding creado en cada renderizado
@State var name = ""
TextField("Nombre", text: Binding(
get: { name },
set: { name = $0 }
)) // Nuevo objeto binding cada vez que el padre renderiza
// ✅ CORRECTO: Pasa el binding real
@State var isOn = false
ToggleChild(value: $isOn)
// ✅ CORRECTO (iOS 17+): Usa @Bindable para objetos @Observable
@Observable class Book {
var title = "Muestra"
var isAvailable = true
}
struct EditView: View {
@Bindable var book: Book // Habilita la sintaxis $book.title
var body: some View {
TextField("Título", text: $book.title)
Toggle("Disponible", isOn: $book.isAvailable)
}
}
// ✅ TAMBIÉN CORRECTO (iOS 17+): @Bindable como variable local
struct ListView: View {
@State private var books = [Book(), Book()]
var body: some View {
List(books) { book in
@Bindable var book = book // Binding en línea
TextField("Título", text: $book.title)
}
}
}
// ✅ CORRECTO (pre-iOS 17): Crea el binding una vez, no en body
@State var name = ""
@State var nameBinding: Binding<String>?
var body: some View {
if nameBinding == nil {
nameBinding = Binding(
get: { name },
set: { name = $0 }
)
}
return TextField("Nombre", text: nameBinding!)
}
Arrglalo: Pasa $state directamente cuando sea posible. Para objetos @Observable (iOS 17+), usa @Bindable. Si creas bindings personalizados (pre-iOS 17), créalos en init o guardáelos en caché, no en body.
Causa raíz 3: Recreación accidental de la vista
Síntoma: La vista se actualiza, pero los valores @State se restablecen al estado inicial. Ves breves destellos de valores iniciales.
Por qué ocurre: La vista obtuvo una nueva identidad (eliminada de un condicional, movida en un contenedor, o el propio contenedor fue recreado), lo que hace que SwiftUI la trate como una vista nueva.
// ❌ INCORRECTO: La identidad de la vista cambia cuando la condición cambia
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter() // Obtiene una nueva identidad cada vez que showCounter cambia
}
Button("Alternar") {
showCounter.toggle()
}
}
}
// Counter se recrea, @State count se reinicia a 0
// ✅ CORRECTO: Preserva la identidad con opacidad u ocultación
@State var count = 0
var body: some View {
VStack {
Counter()
.opacity(showCounter ? 1 : 0)
Button("Alternar") {
showCounter.toggle()
}
}
}
// ✅ TAMBIÉN CORRECTO: Usa id() si debes mostrar condicionalmente
@State var count = 0
var body: some View {
VStack {
if showCounter {
Counter()
.id("counter") // Identidad estable
}
Button("Alternar") {
showCounter.toggle()
}
}
}
Arrglalo: Preserva la identidad de la vista usando .opacity() en lugar de condicionales, o aplica .id() con un identificador estable.
Causa raíz 4: Patrón observador faltante
Síntoma: Un objeto cambió, pero las vistas que lo observaban no se actualizaron.
Por qué ocurre: SwiftUI no sabe que debe vigilar los cambios en el objeto.
// ❌ INCORRECTO: Los cambios de propiedad no desencadenan la actualización
class Model {
var count = 0 // No observable
}
struct ContentView: View {
let model = Model() // Nueva instancia en cada renderizado, no observable
var body: some View {
Text("\(model.count)")
Button("Incrementar") {
model.count += 1 // La vista no se actualiza
}
}
}
// ✅ CORRECTO (iOS 17+): Usa @Observable con @State
@Observable class Model {
var count = 0 // No se necesita @Published
}
struct ContentView: View {
@State private var model = Model() // @State, no @StateObject
var body: some View {
Text("\(model.count)")
Button("Incrementar") {
model.count += 1 // La vista se actualiza
}
}
}
// ✅ CORRECTO (iOS 17+): Objetos @Observable inyectados
struct ContentView: View {
var model: Model // Solo una propiedad simple
var body: some View {
Text("\(model.count)") // La vista se actualiza cuando count cambia
}
}
// ✅ CORRECTO (iOS 17+): @Observable con entorno
@Observable class AppModel {
var count = 0
}
@main
struct MyApp: App {
@State private var model = AppModel()
var body: some Scene {
WindowGroup {
ContentView()
.environment(model) // Añadir al entorno
}
}
}
struct ContentView: View {
@Environment(AppModel.self) private var model // Leer del entorno
var body: some View {
Text("\(model.count)")
}
}
// ✅ CORRECTO (pre-iOS 17): Usa @StateObject/ObservableObject
class Model: ObservableObject {
@Published var count = 0
}
struct ContentView: View {
@StateObject var model = Model() // Para instancias propias
var body: some View {
Text("\(model.count)")
Button("Incrementar") {
model.count += 1 // La vista se actualiza
}
}
}
// ✅ CORRECTO (pre-iOS 17): Usa @ObservedObject para instancias inyectadas
struct ContentView: View {
@ObservedObject var model: Model // Pasado desde el padre
var body: some View {
Text("\(model.count)")
}
}
Arrglalo (iOS 17+): Usa la macro @Observable en tu clase, luego @State para almacenarla. Las vistas rastrean automáticamente las dependencias en las propiedades que leen.
Arrglalo (pre-iOS 17): Usa @StateObject si eres el dueño del objeto, @ObservedObject si se inyecta, o @EnvironmentObject si se comparte en todo el árbol.
Por qué @Observable es mejor (iOS 17+):
- Seguimiento automático de dependencias (solo las lecturas desencadenan actualizaciones)
- No se necesita el wrapper
@Published - Funciona con
@Stateen lugar de@StateObject - Se puede pasar como propiedad simple en lugar de
@ObservedObject
Ver también: Managing model data in your app
Resumen del árbol de decisión
digraph view_not_updating {
start [label="¿La vista no se actualiza?" shape=diamond];
reproduce [label="¿Se puede reproducir en la previsualización?" shape=diamond];
cause [label="¿Qué cambió?" shape=diamond];
start -> reproduce;
reproduce -> cause [label="sí: error en el código"];
reproduce -> "Caché/estado de Xcode → Fallos en previsualización" [label="no"];
cause -> "Mutación de Struct" [label="modificó el struct directamente"];
cause -> "Pérdida de identidad del Binding" [label="pasó un binding al hijo"];
cause -> "Recreación Accidental" [label="vista dentro de un condicional"];
cause -> "Observador Faltante" [label="el objeto cambió, la vista no"];
}
Árbol de decisión: Fallos en la previsualización
Cuando tu previsualización no se carga o falla inmediatamente, las tres causas raíz son distintas.
Paso 1: ¿Cuál es el error?
Tipo de error 1: "Cannot find in scope" o "No such module"
Causa raíz: A la previsualización le falta una dependencia requerida (@EnvironmentObject, @Environment, módulo importado).
// ❌ INCORRECTO: ContentView necesita un modelo, la previsualización no lo proporciona
struct ContentView: View {
@EnvironmentObject var model: AppModel
var body: some View {
Text(model.title)
}
}
#Preview {
ContentView() // Fallo: modelo no encontrado
}
// ✅ CORRECTO: Proporciona la dependencia
#Preview {
ContentView()
.environmentObject(AppModel())
}
// ✅ TAMBIÉN CORRECTO: Verifica las importaciones faltantes
// Si usas tipos personalizados, asegúrate de que estén importados en el archivo de previsualización
#Preview {
MyCustomView() // Asegúrate de que MyCustomView esté definida o importada
}
Arrglalo: Rastrea el error, encuentra lo que falta, proporciónalo a la previsualización.
Tipo de error 2: Error fatal o fallo silencioso (sin mensaje de error)
Causa raíz: La inicialización del estado falló en tiempo de ejecución. La vista intentó acceder a datos que no existen.
// ❌ INCORRECTO: Índice fuera de los límites en tiempo de ejecución
struct ListView: View {
@State var selectedIndex = 10
let items = ["a", "b", "c"]
var body: some View {
Text(items[selectedIndex]) // Fallo: el índice 10 no existe
}
}
// ❌ INCORRECTO: El desempaquetado forzado de opcional falla
struct DetailView: View {
@State var data: Data?
var body: some View {
Text(data!.title) // Fallo si data es nil
}
}
// ✅ CORRECTO: Valores predeterminados seguros
struct ListView: View {
@State var selectedIndex = 0 // Índice válido
let items = ["a", "b", "c"]
var body: some View {
if selectedIndex < items.count {
Text(items[selectedIndex])
}
}
}
// ✅ CORRECTO: Manejar opcionales
struct DetailView: View {
@State var data: Data?
var body: some View {
if let data = data {
Text(data.title)
} else {
Text("No hay datos")
}
}
}
Arrglalo: Asegúrate de que todos los datos a los que se accede durante la inicialización existan y sean válidos.
Tipo de error 3: "Editor placeholder" o "Build failed" con código válido
Causa raíz: Caché de Xcode dañada. Xcode está usando datos de previsualización obsoletos o corruptos.
Pasos para limpiar:
- Limpiar la carpeta de Derived Data:
rm -rf ~/Library/Developer/Xcode/DerivedData - Limpiar la carpeta de Previews:
rm -rf ~/Library/Developer/Xcode/UserData/Previews - Reiniciar Xcode y probar de nuevo.
Arrglalo: Borra las carpetas de Derived Data y Previews, luego reinicia Xcode. Si el problema persiste, el skill axiom-xcode-debugging proporciona diagnósticos más profundos.
Resumen del árbol de decisión
digraph preview_crashes {
start [label="¿La previsualización falla?" shape=diamond];
error [label="¿Qué error ves?" shape=diamond];
start -> error;
error -> "Proporcionar dependencia" [label="'Cannot find in scope' o 'No such module'"];
error -> "Verificar datos de inicialización" [label="Fallo fatal o silencio"];
error -> "Limpiar Derived Data / Previews" [label="'Editor placeholder' o 'Build failed'"];
}
Referencia rápida de problemas de diseño
La depuración de diseño es específica del contexto, pero aquí hay patrones comunes.
1. La vista se superpone inesperadamente
Causa: Los modificadores de diseño se aplican al contenedor incorrecto o faltan modificadores a nivel de contenedor.
// ❌ INCORRECTO: Los modificadores en VStack no espacian los elementos hijos
VStack {
Image(systemName: "globe")
.resizable()
.frame(width: 50, height: 50)
Text("Hola, mundo!")
}
// Los elementos aparecen uno encima del otro porque no se especifica spacing
// ✅ CORRECTO: Establece el spacing explícitamente en el contenedor
VStack(spacing: 12) {
Image(systemName: "globe")
.resizable()
.frame(width: 50, height: 50)
Text("Hola, mundo!")
}
// ✅ CORRECTO: Usa un Spacer para llenar el espacio
VStack {
Spacer()
Image(systemName: "globe")
.resizable()
.frame(width: 50, height: 50)
Spacer()
Text("Hola, mundo!")
}
Arrglalo: Asegúrate de que el contenedor (VStack, HStack, ZStack) tenga el spacing correcto y/o Spacers.
2. La vista tiene el tamaño incorrecto
Causa: Un .frame() en un contenedor no funciona como se espera, o el contenedor no está ocupando todo el espacio disponible.
// ❌ INCORRECTO: Establecer frame en VStack no funciona si no está usando .frame(maxWidth: .infinity)
VStack {
Text("Hola")
}
.frame(width: 300) // VStack se centra, no ocupa 300pt
// ✅ CORRECTO: Usa .frame() con maxWidth
VStack {
Text("Hola")
}
.frame(maxWidth: .infinity, alignment: .leading) // Ocupa todo el ancho
// ✅ CORRECTO: Usa .containerRelativeFrame() para tamaños relativos
VStack {
Text("Hola")
}
.containerRelativeFrame(.vertical) { height, axis in
height * 0.5 // La mitad de la altura del contenedor
}
Arrglalo: Si necesitas que un contenedor tenga un tamaño específico, usa .frame(maxWidth: .infinity, maxHeight: .infinity) y aplica la alineación.
3. El texto se trunca o se superpone cuando la fuente es grande
Causa: Faltan modificadores de ajuste de texto o de escala de fuente.
// ❌ INCORRECTO: Texto largo se trunca sin opción de ajuste
Text("Un texto muy largo que probablemente se truncará en dispositivos pequeños")
// ✅ CORRECTO: Permite que el texto se ajuste a varias líneas
Text("Un texto muy largo que probablemente se truncará en dispositivos pequeños")
.lineLimit(nil) // Permite líneas ilimitadas
// ✅ CORRECTO: Escala la fuente para que se ajuste a una línea
Text("Un texto muy largo que se escalará para ajustarse")
.minimumScaleFactor(0.5) // Escala hasta el 50%
.lineLimit(1)
// ✅ CORRECTO: Usa Dynamic Type para fuentes adaptativas
Text("Texto adaptativo")
.font(.body) // Usa la fuente del sistema que escala con Dynamic Type
Arrglalo: Aplica .lineLimit(), .minimumScaleFactor(), o usa una fuente que soporte Dynamic Type.
4. La vista se sale de los límites de la pantalla
Causa: Las vistas no se están limitando al área segura o se están saliendo de la pantalla.
// ❌ INCORRECTO: Ignorar el área segura sin la gestión adecuada del diseño
VStack {
Text("Arriba")
Spacer()
Text("Abajo")
}
.ignoresSafeArea() // Ignora toda la guía de diseño, los elementos pueden estar debajo de la barra de estado
// ✅ CORRECTO: Ignorar el área segura solo en los bordes necesarios
VStack {
Text("Arriba")
.padding(.top) // Asegura que esté debajo de la barra de estado
Spacer()
Text("Abajo")
.padding(.bottom) // Asegura que esté por encima del indicador de home
}
.ignoresSafeArea(.all, edges: .bottom) // Ignora solo la parte inferior
// ✅ CORRECTO: Usa .safeAreaPadding() (iOS 17+)
VStack {
Text("Arriba")
Spacer()
Text("Abajo")
}
.safeAreaPadding() // Añade padding basado en el área segura
Arrglalo: Usa .ignoresSafeArea() con moderación y siempre aplica padding o usa .safeAreaPadding() para respetar el área segura.
5. El rendimiento del diseño es lento
Causa: Las vistas se están recalculando innecesariamente o se utilizan contenedores complejos.
Consejos:
- Usa
LazyVStackyLazyHStackpara listas largas - Evita los GeometryReaders anidados
- Usa id estables para las vistas de lista
- Perfila con Instruments (skill
axiom-swiftui-performancepara más detalles)
// ❌ INCORRECTO: GeometryReader anidado que se reajusta constantemente
GeometryReader { outer in
VStack {
ForEach(items) { item in
GeometryReader { inner in
Text(item.name)
.frame(width: inner.size.width)
}
}
}
}
// ✅ CORRECTO: Mide una vez, usa en todas partes
let itemWidth: CGFloat = 100
ListView {
ForEach(items) { item in
Text(item.name)
.frame(width: itemWidth)
}
}
Arrglalo: Simplifica la jerarquía de vistas, usa listas perezosas y evita los GeometryReaders anidados.
Notas de versión
- iOS 14-16: Usa ObservableObject con @Published/@StateObject/@ObservedObject
- iOS 17+: Usa @Observable con @State (más simple)
- Xcode 26+: Soporta todas las características de iOS 17+
- SwiftUI Instrument: disponible en Xcode 15+ para perfilado detallado de actualizaciones