PreviewProvider — qué es, protocolo SwiftUI y configuración en Xcode

¿Qué es PreviewProvider?

PreviewProvider es un protocolo SwiftUI que define un contrato para crear contenido de vista previa en Xcode Canvas. El protocolo contiene una única propiedad obligatoria: previews de tipo some View. Cualquier valor devuelto por previews se muestra en Canvas como una vista previa interactiva. PreviewProvider no requiere herencia — basta con una implementación estática en una extensión.

Arquitectónicamente, PreviewProvider no forma parte del runtime de SwiftUI — es exclusivamente una herramienta de desarrollo. El protocolo está marcado con el atributo @available(iOS 13.0, *) y no se compila en la versión de lanzamiento, ya que Xcode utiliza compilación condicional para excluir el código de vista previa de producción. Esto significa que PreviewProvider no afecta al tamaño del binario ni al rendimiento de la aplicación.

El protocolo previews

La propiedad previews es el único requisito de PreviewProvider. Debe devolver cualquier View: desde un simple Text hasta una jerarquía compleja con Group y ForEach. Xcode renderiza la View devuelta en Canvas, aplicando la configuración del sistema (tema, tamaño, fuente).

import SwiftUI

struct GreetingView: View {
    let name: String
    
    var body: some View {
        Text("Hello, \(name)!")
            .padding()
    }
}

// PreviewProvider — static implementation
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Convención de nomenclatura: Apple recomienda nombrar la estructura de vista previa como {ViewName}_Previews. No es un requisito del compilador, pero mejora la legibilidad y la navegación por el proyecto. Xcode inserta automáticamente esta plantilla al crear un nuevo archivo SwiftUI.

Cómo funciona PreviewProvider: protocolo y método previews

El mecanismo de funcionamiento de PreviewProvider se basa en la despachación estática: Xcode compila la extensión PreviewProvider solo para la configuración Debug y llama a previews durante el proceso de construcción de Canvas. Cada vez que el código cambia, Xcode recompila solo los PreviewProvider modificados, garantizando actualizaciones casi instantáneas de la vista previa.

SwiftUI no garantiza una coincidencia exacta entre la vista previa y la interfaz final en un simulador o dispositivo — Canvas utiliza un renderizado simplificado. Las animaciones con retrasos pueden mostrarse incorrectamente, y algunos componentes UIKit (MapKit, WebView) no se renderizan en Canvas sin configuración adicional.

Múltiples vistas previas mediante Group

Group permite mostrar varios estados de una misma View simultáneamente, acelerando la iteración al diseñar diferentes configuraciones. Cada vista previa dentro de Group se renderiza de forma independiente.

struct ButtonView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ButtonView(title: "Primary", style: .primary)
                .previewDisplayName("Primary")
            
            ButtonView(title: "Disabled", style: .primary)
                .disabled(true)
                .previewDisplayName("Disabled")
            
            ButtonView(title: "Secondary", style: .secondary)
                .previewDisplayName("Secondary")
        }
    }
}

previewDisplayName añade una etiqueta a cada vista previa en Canvas, lo que resulta especialmente útil al comparar varios estados. El número máximo de vistas previas en Group no está limitado, pero más de 6–8 ralentizan Canvas.

Configuración de vistas previas en Xcode

Xcode proporciona varios modificadores para configurar la visualización de las vistas previas. Los principales: previewDevice — emula un dispositivo específico (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — establece el tamaño (device, fixed, sizeThatFits). La combinación de estos modificadores ofrece un control total sobre el entorno de vista previa.

previewDevice acepta una cadena con el nombre del dispositivo, por ejemplo "iPhone 16 Pro" o "iPad Pro 13-inch (M4)". La lista de dispositivos disponibles depende de los simuladores instalados en Xcode. Si no se encuentra el dispositivo, Canvas muestra la vista previa en el dispositivo predeterminado sin error.

Vistas previas para diferentes dispositivos

Práctica común es mostrar una misma View en varios dispositivos simultáneamente para comprobar la adaptabilidad. Para ello se utiliza ForEach con un array de nombres de dispositivos.

struct AdaptiveView_Previews: PreviewProvider {
    static var previews: some View {
        ForEach(["iPhone SE (3rd generation)", "iPhone 16 Pro Max", "iPad Pro 13-inch (M4)"], id: \.self) { device in
            AdaptiveView()
                .previewDevice(.previewDevice(device))
                .previewDisplayName(device)
        }
    }
}

Ejemplos de PreviewProvider

Ejemplos prácticos muestran varios escenarios de uso de PreviewProvider: desde vistas previas simples hasta configuraciones complejas con datos reales y compatibilidad con UIKit.

Vista previa con datos simulados

Los datos simulados son un patrón estándar para vistas previas cuando una View acepta un modelo. En lugar de una API real, se sustituyen datos de prueba, lo que permite verificar visualmente el estado de la interfaz sin iniciar la aplicación.

struct UserProfileView: View {
    let user: User
    
    var body: some View {
        VStack {
            AsyncImage(url: user.avatarURL)
                .clipShape(Circle())
            Text(user.name)
                .font(.title)
            Text(user.bio)
                .font(.body)
                .foregroundColor(.secondary)
        }
    }
}

struct UserProfileView_Previews: PreviewProvider {
    static var previews: some View {
        UserProfileView(user: .mock)
            .previewDisplayName("Profile")
        
        UserProfileView(user: .mockLongName)
            .previewDisplayName("Long Name")
    }
}

Vista previa UIKit mediante UIViewRepresentable

Compatibilidad con UIKit — PreviewProvider también funciona con componentes UIKit envueltos en UIViewRepresentable. Esto permite previsualizar vistas UIKit existentes en SwiftUI Canvas sin migrar todo el proyecto.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // Configure map
    }
}

struct MapView_Previews: PreviewProvider {
    static var previews: some View {
        MapViewRepresentable()
    }
}

PreviewProvider y SwiftUI Canvas

Canvas es el editor visual de Xcode que renderiza la salida de PreviewProvider en tiempo real. Sin una implementación de PreviewProvider, Canvas permanece vacío. Canvas y PreviewProvider funcionan en conjunto: PreviewProvider define qué mostrar, Canvas define dónde y cómo.

Es importante entender: Canvas es el entorno de ejecución de la vista previa, no una alternativa a PreviewProvider. Incluso si el desarrollador no abre Canvas, PreviewProvider puede utilizarse para una verificación rápida del código mediante la vista previa emergente al pasar el ratón sobre el icono de Canvas. Según WWDC 2024, Apple recomienda escribir PreviewProvider para cada View como estándar de desarrollo, similar a la escritura de pruebas unitarias.

Recomendación: escriba PreviewProvider para cada View pública del proyecto. Esto acelera la incorporación de nuevos desarrolladores, simplifica las revisiones de código y permite verificar rápidamente los cambios visuales sin compilar todo el proyecto.

Problemas comunes con PreviewProvider

Problema 1: La vista previa no se actualiza. Si Canvas no refleja los cambios de código, la causa suele ser la caché de DerivedData. Limpie DerivedData mediante Product → Clean Build Folder (⇧⌘K) o eliminando manualmente la carpeta ~/Library/Developer/Xcode/DerivedData. Tras la limpieza, Canvas reconstruye la vista previa desde cero.

Problema 2: PreviewProvider no ve @StateObject. PreviewProvider crea una instancia estática de la View, por lo que las dependencias que requieren inyección (ViewModels, servicios) deben pasarse a través del inicializador o @StateObject con un valor predeterminado. Utilice objetos simulados en lugar de servicios reales en las vistas previas.

Problema 3: Las animaciones no funcionan en Canvas. Canvas no admite todas las animaciones de SwiftUI — especialmente las que dependen del tiempo (withAnimation con retraso, .spring). Para probar animaciones, ejecute la aplicación en un simulador. Canvas es adecuado para la verificación estática del diseño.

Solución de PreviewProvider con dependencias

La inyección de dependencias es la mejor manera de hacer que PreviewProvider funcione con ViewModels complejos. Cree una instancia separada de ViewModel con datos de prueba y pásela al inicializador de la View.

struct DashboardView: View {
    @StateObject var viewModel: DashboardViewModel
    
    var body: some View {
        List(viewModel.items) { item in
            Text(item.title)
        }
    }
}

struct DashboardView_Previews: PreviewProvider {
    static var previews: some View {
        DashboardView(viewModel: DashboardViewModel.mock)
    }
}

Extensiones simuladas: cree una extensión para el ViewModel que proporcione instancias .mock estáticas. Esto mantiene los datos de prueba cerca del ViewModel y hace que PreviewProvider sea legible.