PreviewProvider — o que é, protocolo SwiftUI e configuração no Xcode

O que é PreviewProvider?

PreviewProvider é um protocolo SwiftUI que define um contrato para criar conteúdo de pré-visualização no Xcode Canvas. O protocolo contém uma única propriedade obrigatória: previews do tipo some View. Qualquer valor retornado por previews é exibido no Canvas como uma pré-visualização interativa. O PreviewProvider não requer herança — basta uma implementação estática numa extensão.

Arquiteturalmente, o PreviewProvider não faz parte do runtime SwiftUI — é exclusivamente uma ferramenta de desenvolvimento. O protocolo está marcado com o atributo @available(iOS 13.0, *) e não é compilado na versão de lançamento, pois o Xcode usa compilação condicional para excluir o código de pré-visualização da produção. Isso significa que o PreviewProvider não afeta o tamanho do binário nem o desempenho da aplicação.

O protocolo previews

A propriedade previews é o único requisito do PreviewProvider. Deve retornar qualquer View: desde um simples Text até uma hierarquia complexa com Group e ForEach. O Xcode renderiza a View retornada no Canvas, aplicando as configurações do sistema (tema, tamanho, fonte).

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")
    }
}

Convenção de nomenclatura: a Apple recomenda nomear a estrutura de pré-visualização como {ViewName}_Previews. Não é um requisito do compilador, mas melhora a legibilidade e a navegação no projeto. O Xcode insere automaticamente este modelo ao criar um novo ficheiro SwiftUI.

Como funciona o PreviewProvider: protocolo e método previews

O mecanismo de funcionamento do PreviewProvider baseia-se em despacho estático: o Xcode compila a extensão PreviewProvider apenas para a configuração Debug e chama previews durante o processo de construção do Canvas. Cada vez que o código muda, o Xcode recompila apenas os PreviewProviders modificados, garantindo atualizações quase instantâneas da pré-visualização.

SwiftUI não garante uma correspondência exata entre a pré-visualização e a interface final num simulador ou dispositivo — o Canvas utiliza renderização simplificada. Animações com atrasos podem ser exibidas incorretamente e alguns componentes UIKit (MapKit, WebView) não são renderizados no Canvas sem configuração adicional.

Múltiplas pré-visualizações através de Group

Group permite exibir vários estados de uma mesma View simultaneamente, acelerando a iteração ao criar diferentes configurações. Cada pré-visualização dentro de Group é renderizada independentemente.

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 adiciona uma etiqueta a cada pré-visualização no Canvas, o que é especialmente útil ao comparar vários estados. O número máximo de pré-visualizações em Group não é limitado, mas mais de 6–8 tornam o Canvas mais lento.

Configuração de pré-visualizações no Xcode

O Xcode fornece vários modificadores para configurar a exibição da pré-visualização. Os principais: previewDevice — simula um dispositivo específico (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — define o tamanho (device, fixed, sizeThatFits). A combinação destes modificadores dá controlo total sobre o ambiente de pré-visualização.

previewDevice aceita uma string com o nome do dispositivo, por exemplo "iPhone 16 Pro" ou "iPad Pro 13-inch (M4)". A lista de dispositivos disponíveis depende dos simuladores instalados no Xcode. Se o dispositivo não for encontrado, o Canvas exibe a pré-visualização no dispositivo predefinido sem erro.

Pré-visualizações para diferentes dispositivos

Prática comum é exibir uma mesma View em vários dispositivos simultaneamente para verificar a adaptabilidade. Para tal, utiliza-se ForEach com um array de nomes 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)
        }
    }
}

Exemplos de PreviewProvider

Exemplos práticos mostram vários cenários de utilização do PreviewProvider: desde pré-visualizações simples até configurações complexas com dados reais e compatibilidade UIKit.

Pré-visualização com dados simulados

Dados simulados são um padrão standard para pré-visualizações quando uma View aceita um modelo. Em vez de uma API real, são substituídos dados de teste, permitindo a verificação visual do estado da interface sem iniciar a aplicação.

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")
    }
}

Pré-visualização UIKit através de UIViewRepresentable

Compatibilidade UIKit — o PreviewProvider também funciona com componentes UIKit encapsulados em UIViewRepresentable. Isto permite pré-visualizar vistas UIKit existentes no SwiftUI Canvas sem migrar todo o projeto.

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 e SwiftUI Canvas

Canvas é o editor visual do Xcode que renderiza a saída do PreviewProvider em tempo real. Sem uma implementação PreviewProvider, o Canvas permanece vazio. Canvas e PreviewProvider funcionam em conjunto: PreviewProvider define o que mostrar, Canvas define onde e como.

É importante entender: Canvas é o ambiente de execução da pré-visualização, não uma alternativa ao PreviewProvider. Mesmo que o desenvolvedor não abra o Canvas, o PreviewProvider pode ser usado para verificação rápida do código através da pré-visualização popup ao passar o rato sobre o ícone do Canvas. De acordo com a WWDC 2024, a Apple recomenda escrever PreviewProvider para cada View como padrão de desenvolvimento, semelhante à escrita de testes unitários.

Recomendação: escreva PreviewProvider para cada View pública no projeto. Isto acelera a integração de novos programadores, simplifica a revisão de código e permite verificar rapidamente alterações visuais sem compilar todo o projeto.

Problemas comuns com PreviewProvider

Problema 1: A pré-visualização não atualiza. Se o Canvas não refletir as alterações de código, a causa é geralmente a cache DerivedData. Limpe a DerivedData através de Product → Clean Build Folder (⇧⌘K) ou apagando manualmente a pasta ~/Library/Developer/Xcode/DerivedData. Após a limpeza, o Canvas reconstrói a pré-visualização de raiz.

Problema 2: PreviewProvider não vê @StateObject. O PreviewProvider cria uma instância estática da View, pelo que as dependências que requerem injeção (ViewModels, serviços) devem ser passadas através do inicializador ou @StateObject com um valor predefinido. Use objetos simulados em vez de serviços reais nas pré-visualizações.

Problema 3: Animações não funcionam no Canvas. O Canvas não suporta todas as animações SwiftUI — especialmente as que dependem de temporização (withAnimation com atraso, .spring). Para testar animações, execute a aplicação num simulador. O Canvas é adequado para verificação estática de layout.

Corrigir PreviewProvider com dependências

Injeção de dependências é a melhor forma de fazer o PreviewProvider funcionar com ViewModels complexos. Crie uma instância separada do ViewModel com dados de teste e passe-a para o inicializador da 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)
    }
}

Extensões simuladas: crie uma extensão para o ViewModel que forneça instâncias .mock estáticas. Isto mantém os dados de teste perto do ViewModel e torna o PreviewProvider legível.