PreviewProvider — apa itu, protokol SwiftUI dan konfigurasi di Xcode

Apa itu PreviewProvider?

PreviewProvider — protokol SwiftUI yang mendefinisikan kontrak untuk membuat konten pratinjau di Xcode Canvas. Protokol berisi satu properti wajib: previews bertipe some View. Nilai apa pun yang dikembalikan oleh previews ditampilkan di Canvas sebagai pratinjau interaktif. PreviewProvider tidak memerlukan pewarisan — implementasi statis di extension sudah cukup.

Secara arsitektur, PreviewProvider bukan bagian dari runtime SwiftUI — ini semata-mata alat pengembangan. Protokol ditandai dengan atribut @available(iOS 13.0, *) dan tidak dikompilasi dalam build rilis, karena Xcode menggunakan kompilasi bersyarat untuk mengecualikan kode pratinjau dari produksi. Ini berarti PreviewProvider tidak memengaruhi ukuran biner dan kinerja aplikasi.

Protokol previews

Properti previews — satu-satunya persyaratan PreviewProvider. Harus mengembalikan View apa pun: dari Text sederhana hingga hierarki kompleks dengan Group dan ForEach. Xcode merender View yang dikembalikan di Canvas, menerapkan pengaturan sistem (tema, ukuran, font).

import SwiftUI

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

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

Konvensi penamaan: Apple merekomendasikan penamaan struktur pratinjau sebagai {ViewName}_Previews. Ini bukan persyaratan wajib kompiler, tetapi meningkatkan keterbacaan dan navigasi proyek. Xcode secara otomatis mengganti template ini saat membuat file SwiftUI baru.

Cara kerja PreviewProvider: protokol dan metode previews

Mekanisme kerja PreviewProvider didasarkan pada pengiriman statis: Xcode mengompilasi extension dengan PreviewProvider hanya untuk konfigurasi Debug dan memanggil previews selama proses pembuatan Canvas. Setiap kali kode berubah, Xcode hanya mengompilasi ulang PreviewProvider yang diubah, memastikan pembaruan pratinjau hampir seketika.

SwiftUI tidak menjamin kecocokan persis pratinjau dengan UI akhir pada simulator atau perangkat — Canvas menggunakan rendering yang disederhanakan. Animasi dengan penundaan mungkin ditampilkan secara tidak benar, dan beberapa komponen UIKit (MapKit, WebView) tidak dirender di Canvas tanpa konfigurasi tambahan.

Pratinjau ganda melalui Group

Group memungkinkan menampilkan beberapa status dari satu View secara bersamaan, yang mempercepat iterasi saat mendesain berbagai konfigurasi. Setiap pratinjau di dalam Group dirender secara independen.

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 menambahkan label ke setiap pratinjau di Canvas, yang sangat berguna saat membandingkan beberapa status. Jumlah maksimum pratinjau di Group tidak terbatas, tetapi lebih dari 6–8 memperlambat Canvas.

Konfigurasi pratinjau di Xcode

Xcode menyediakan beberapa pengubah untuk mengonfigurasi tampilan pratinjau. Yang utama: previewDevice — meniru perangkat tertentu (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — mengatur ukuran (device, fixed, sizeThatFits). Kombinasi pengubah ini memberikan kendali penuh atas lingkungan pratinjau.

previewDevice menerima string dengan nama perangkat, misalnya “iPhone 16 Pro” atau “iPad Pro 13-inch (M4)”. Daftar perangkat yang tersedia tergantung pada simulator yang terinstal di Xcode. Jika perangkat tidak ditemukan, Canvas menampilkan pratinjau pada perangkat default tanpa kesalahan.

Pratinjau untuk berbagai perangkat

Praktik umum — menampilkan satu View di beberapa perangkat secara bersamaan untuk memeriksa responsivitas. Untuk ini, ForEach dengan array nama perangkat digunakan.

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

Contoh PreviewProvider

Contoh praktis menunjukkan berbagai skenario penggunaan PreviewProvider: dari pratinjau sederhana hingga konfigurasi kompleks dengan data langsung dan kompatibilitas UIKit.

Pratinjau dengan data tiruan

Data tiruan — pola standar untuk pratinjau saat View menerima model. Alih-alih API nyata, data uji disubstitusi, memungkinkan pemeriksaan visual status UI tanpa menjalankan aplikasi.

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

Pratinjau UIKit melalui UIViewRepresentable

Kompatibilitas UIKit — PreviewProvider juga berfungsi dengan komponen UIKit yang dibungkus dalam UIViewRepresentable. Ini memungkinkan pratinjau tampilan UIKit yang ada di SwiftUI Canvas tanpa migrasi seluruh proyek.

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

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

PreviewProvider dan SwiftUI Canvas

Canvas — adalah editor visual Xcode yang merender hasil PreviewProvider secara real-time. Tanpa implementasi PreviewProvider, Canvas tetap kosong. Canvas dan PreviewProvider bekerja berpasangan: PreviewProvider menentukan apa yang ditampilkan, Canvas — di mana dan bagaimana.

Penting untuk dipahami: Canvas — adalah lingkungan eksekusi pratinjau, bukan alternatif untuk PreviewProvider. Bahkan jika pengembang tidak membuka Canvas, PreviewProvider dapat digunakan untuk pemeriksaan kode cepat melalui pratinjau yang muncul saat mengarahkan kursor ke ikon Canvas. Menurut WWDC 2024, Apple merekomendasikan penulisan PreviewProvider untuk setiap View sebagai standar pengembangan, mirip dengan penulisan unit test.

Rekomendasi: tulis PreviewProvider untuk setiap View publik di proyek. Ini mempercepat orientasi pengembang baru, menyederhanakan tinjauan kode, dan memungkinkan pemeriksaan cepat perubahan visual tanpa membangun seluruh proyek.

Masalah umum dengan PreviewProvider

Masalah 1: Pratinjau tidak diperbarui. Jika Canvas tidak mencerminkan perubahan kode, penyebabnya biasanya adalah cache DerivedData. Bersihkan DerivedData melalui Product → Clean Build Folder (⇧⌘K) atau dengan menghapus folder ~/Library/Developer/Xcode/DerivedData secara manual. Setelah pembersihan, Canvas membangun ulang pratinjau dari awal.

Masalah 2: PreviewProvider tidak melihat @StateObject. PreviewProvider membuat instance statis View, sehingga dependensi yang memerlukan injeksi (ViewModel, layanan) harus diteruskan melalui penginisialisasi atau @StateObject dengan nilai default. Gunakan objek tiruan alih-alih layanan nyata dalam pratinjau.

Masalah 3: Animasi tidak berfungsi di Canvas. Canvas tidak mendukung semua animasi SwiftUI — terutama yang bergantung pada waktu (withAnimation dengan penundaan, .spring). Untuk memeriksa animasi, jalankan aplikasi di simulator. Canvas cocok untuk pemeriksaan tata letak statis.

Memperbaiki PreviewProvider dengan dependensi

Injeksi dependensi — cara terbaik untuk membuat PreviewProvider berfungsi dengan ViewModel kompleks. Buat instance ViewModel terpisah dengan data uji dan teruskan ke penginisialisasi 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)
    }
}

Ekstensi tiruan: buat extension untuk ViewModel yang menyediakan instance .mock statis. Ini menjaga data uji tetap dekat dengan ViewModel dan membuat PreviewProvider mudah dibaca.