PreviewProvider — nedir, SwiftUI protokolü ve Xcode'da kurulum

PreviewProvider Nedir?

PreviewProvider, Xcode Canvas'ta önizleme içeriği oluşturmak için bir sözleşme tanımlayan SwiftUI protokolüdür. Protokol, zorunlu bir özellik içerir: previews (türü some View). previews tarafından döndürülen her değer, Canvas'ta etkileşimli bir önizleme olarak görüntülenir. PreviewProvider miras gerektirmez — bir extension'da statik uygulama yeterlidir.

Mimari olarak, PreviewProvider SwiftUI çalışma zamanının bir parçası değildir — tamamen bir geliştirme aracıdır. Protokol, @available(iOS 13.0, *) özniteliği ile işaretlenmiştir ve sürüm derlemesinde derlenmez, çünkü Xcode, önizleme kodunu üretimden hariç tutmak için koşullu derleme kullanır. Bu, PreviewProvider'ın ikili dosya boyutunu veya uygulama performansını etkilemediği anlamına gelir.

previews Protokolü

previews özelliği, PreviewProvider'ın tek gereksinimidir. Basit bir Text'ten Group ve ForEach ile karmaşık bir hiyerarşiye kadar herhangi bir View döndürmelidir. Xcode, döndürülen View'i Canvas'ta işleyerek sistem ayarlarını (tema, boyut, yazı tipi) uygular.

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

Adlandırma kuralı: Apple, önizleme yapısının {ViewName}_Previews olarak adlandırılmasını önerir. Bu bir derleyici gereksinimi değildir, ancak okunabilirliği ve proje gezinmesini iyileştirir. Xcode, yeni bir SwiftUI dosyası oluştururken otomatik olarak bu şablonu ekler.

PreviewProvider Nasıl Çalışır: Protokol ve previews Yöntemi

Çalışma mekanizması PreviewProvider, statik dağıtıma dayanır: Xcode, PreviewProvider extension'ını yalnızca Debug yapılandırması için derler ve Canvas oluşturma süreci sırasında previews'i çağırır. Kod her değiştiğinde, Xcode yalnızca değiştirilen PreviewProvider'ları yeniden derleyerek neredeyse anında önizleme güncellemeleri sağlar.

SwiftUI, bir simülatör veya cihazda önizleme ile nihai kullanıcı arayüzü arasında tam bir eşleşme garanti etmez — Canvas basitleştirilmiş işleme kullanır. Gecikmeli animasyonlar yanlış görüntülenebilir ve bazı UIKit bileşenleri (MapKit, WebView) ek yapılandırma olmadan Canvas'ta işlenmez.

Group ile Birden Çok Önizleme

Group, bir View'in birden çok durumunu aynı anda görüntülemeye izin vererek farklı yapılandırmaları yerleştirirken yinelemeyi hızlandırır. Group içindeki her önizleme bağımsız olarak işlenir.

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, Canvas'taki her önizlemeye bir etiket ekler; bu, birden çok durumu karşılaştırırken özellikle kullanışlıdır. Group'taki maksimum önizleme sayısı sınırlı değildir, ancak 6–8'den fazlası Canvas'ı yavaşlatır.

Xcode'ta Önizleme Yapılandırması

Xcode, önizleme görüntülemesini yapılandırmak için birkaç değiştirici sağlar. Başlıcaları: previewDevice — belirli bir cihazı öykünür (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — boyutu ayarlar (device, fixed, sizeThatFits). Bu değiştiricilerin kombinasyonu, önizleme ortamı üzerinde tam kontrol sağlar.

previewDevice, cihaz adını içeren bir dize kabul eder, örneğin "iPhone 16 Pro" veya "iPad Pro 13-inch (M4)". Kullanılabilir cihazların listesi, Xcode'ta yüklü simülatörlere bağlıdır. Cihaz bulunamazsa, Canvas hata vermeden varsayılan cihazda önizlemeyi görüntüler.

Farklı Cihazlar için Önizlemeler

Yaygın uygulama, uyarlanabilirliği kontrol etmek için bir View'i aynı anda birden çok cihazda göstermektir. Bunun için cihaz adlarından oluşan bir dizi ile ForEach kullanılır.

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

PreviewProvider Örnekleri

Pratik örnekler, basit önizlemelerden canlı veri ve UIKit uyumluluğu ile karmaşık yapılandırmalara kadar PreviewProvider'ın çeşitli kullanım senaryolarını gösterir.

Mock Verilerle Önizleme

Mock veriler, bir View bir model kabul ettiğinde önizlemeler için standart bir desendir. Gerçek bir API yerine test verileri kullanılır ve uygulama başlatılmadan kullanıcı arayüzü durumunun görsel olarak doğrulanmasına olanak tanır.

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

UIViewRepresentable ile UIKit Önizlemesi

UIKit uyumluluğu — PreviewProvider, UIViewRepresentable içine sarılmış UIKit bileşenleriyle de çalışır. Bu, projenin tamamını taşımadan mevcut UIKit görünümlerini SwiftUI Canvas'ta önizlemeye olanak tanır.

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

Canvas, PreviewProvider'ın çıktısını gerçek zamanlı olarak işleyen Xcode'un görsel düzenleyicisidir. Bir PreviewProvider uygulaması olmadan Canvas boş kalır. Canvas ve PreviewProvider birlikte çalışır: PreviewProvider ne gösterileceğini tanımlar, Canvas nerede ve nasıl gösterileceğini tanımlar.

Önemli olan şudur: Canvas, önizleme yürütme ortamıdır, PreviewProvider'ın alternatifi değildir. Geliştirici Canvas'ı açmasa bile, PreviewProvider Canvas simgesinin üzerine gelindiğinde açılır önizleme yoluyla hızlı kod kontrolü için kullanılabilir. WWDC 2024'e göre Apple, birim testleri yazmaya benzer şekilde, her View için PreviewProvider yazılmasını bir geliştirme standardı olarak önerir.

Öneri: projedeki her genel View için PreviewProvider yazın. Bu, yeni geliştiricilerin işe alımını hızlandırır, kod incelemelerini basitleştirir ve tüm projeyi derlemeden görsel değişikliklerin hızlı bir şekilde doğrulanmasını sağlar.

PreviewProvider ile Sık Karşılaşılan Sorunlar

Sorun 1: Önizleme güncellenmiyor. Canvas kod değişikliklerini yansıtmıyorsa, nedeni genellikle DerivedData önbelleğidir. Product → Clean Build Folder (⇧⌘K) ile DerivedData'yı temizleyin veya ~/Library/Developer/Xcode/DerivedData klasörünü manuel olarak silin. Temizlikten sonra Canvas, önizlemeyi sıfırdan yeniden oluşturur.

Sorun 2: PreviewProvider @StateObject'i görmüyor. PreviewProvider, View'in statik bir örneğini oluşturur, bu nedenle enjeksiyon gerektiren bağımlılıklar (ViewModel'ler, hizmetler) başlatıcı veya varsayılan değere sahip @StateObject aracılığıyla iletilmelidir. Önizlemelerde gerçek hizmetler yerine mock nesneler kullanın.

Sorun 3: Canvas'ta animasyonlar çalışmıyor. Canvas, tüm SwiftUI animasyonlarını desteklemez — özellikle zamana bağlı olanlar (gecikmeli withAnimation, .spring). Animasyonları test etmek için uygulamayı bir simülatörde çalıştırın. Canvas, statik yerleşim doğrulaması için uygundur.

Bağımlılıklarla PreviewProvider'ı Düzeltme

Bağımlılık enjeksiyonu, PreviewProvider'ı karmaşık ViewModel'lerle çalıştırmanın en iyi yoludur. Test verileriyle ayrı bir ViewModel örneği oluşturun ve bunu View başlatıcısına iletin.

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

Mock uzantıları: ViewModel için statik .mock örnekleri sağlayan bir extension oluşturun. Bu, test verilerini ViewModel'in yakınında tutar ve PreviewProvider'ı okunabilir kılar.