PreviewProvider — ano ito, SwiftUI protocol at configuration sa Xcode

Ano ang PreviewProvider?

PreviewProvider — ang SwiftUI protocol na tumutukoy sa kontrata para sa paglikha ng nilalaman ng preview sa Xcode Canvas. Ang protocol ay naglalaman ng isang sapilitang property: previews ng uri na some View. Anumang halaga na ibinalik ng previews ay ipinapakita sa Canvas bilang isang interactive na preview. Ang PreviewProvider ay hindi nangangailangan ng inheritance — sapat na ang static na implementasyon sa extension.

Sa arkitektura, ang PreviewProvider ay hindi bahagi ng SwiftUI runtime — ito ay eksklusibong tool sa pag-develop. Ang protocol ay minarkahan ng @available(iOS 13.0, *) attribute at hindi nagko-compile sa release build, dahil ang Xcode ay gumagamit ng conditional compilation upang ibukod ang preview code mula sa produksyon. Nangangahulugan ito na ang PreviewProvider ay hindi nakakaapekto sa laki ng binary at pagganap ng application.

Protocol previews

Property previews — ang tanging kinakailangan ng PreviewProvider. Dapat itong magbalik ng anumang View: mula sa simpleng Text hanggang sa kumplikadong hierarchy na may Group at ForEach. Ini-render ng Xcode ang ibinalik na View sa Canvas, na inilalapat ang mga setting ng system (tema, laki, font).

import SwiftUI

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

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

Convention sa pagpangalan: Inirerekomenda ng Apple na pangalanan ang preview structure bilang {ViewName}_Previews. Hindi ito sapilitang kinakailangan ng compiler, ngunit pinapabuti nito ang pagiging madaling mabasa at nabigasyon sa proyekto. Awtomatikong pinapalitan ng Xcode ang template na ito kapag lumilikha ng bagong SwiftUI file.

Paano gumagana ang PreviewProvider: protocol at paraan ng previews

Mekanismo ng paggana ng PreviewProvider ay batay sa static dispatch: Xcode ay nagko-compile ng extension na may PreviewProvider para lamang sa Debug configuration at tumatawag sa previews sa proseso ng pagbuo ng Canvas. Sa bawat pagbabago ng code, ang Xcode ay nagre-recompile lamang ng mga binagong PreviewProvider, na tinitiyak ang halos agarang pag-update ng preview.

SwiftUI ay hindi ginagarantiya ang eksaktong pagtutugma ng preview sa huling UI sa simulator o device — ang Canvas ay gumagamit ng pinasimpleng rendering. Ang mga animation na may pagkaantala ay maaaring maipakita nang hindi tama, at ang ilang mga UIKit component (MapKit, WebView) ay hindi nire-render sa Canvas nang walang karagdagang configuration.

Maramihang mga preview sa pamamagitan ng Group

Group ay nagpapahintulot na magpakita ng maraming estado ng isang View nang sabay-sabay, na nagpapabilis ng iteration sa pagdidisenyo ng iba’t ibang configuration. Ang bawat preview sa loob ng Group ay nire-render nang nakapag-iisa.

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 ay nagdaragdag ng label sa bawat preview sa Canvas, na lubhang kapaki-pakinabang kapag naghahambing ng maraming estado. Ang maximum na bilang ng mga preview sa Group ay hindi limitado, ngunit higit sa 6–8 ay nagpapabagal sa Canvas.

Configuration ng preview sa Xcode

Xcode ay nagbibigay ng ilang mga modifier para sa pag-configure ng display ng preview. Ang mga pangunahing: previewDevice — ginagaya ang isang partikular na device (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — nagtatakda ng laki (device, fixed, sizeThatFits). Ang kumbinasyon ng mga modifier na ito ay nagbibigay ng ganap na kontrol sa preview na kapaligiran.

previewDevice ay tumatanggap ng string na may pangalan ng device, halimbawa “iPhone 16 Pro” o “iPad Pro 13-inch (M4)”. Ang listahan ng mga available na device ay depende sa mga naka-install na simulator sa Xcode. Kung hindi natagpuan ang device, ipinapakita ng Canvas ang preview sa default na device nang walang error.

Mga preview para sa iba’t ibang device

Karaniwang praktika — pagpapakita ng isang View sa maraming device nang sabay-sabay upang suriin ang responsiveness. Para dito, ginagamit ang ForEach na may array ng mga pangalan ng device.

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

Mga halimbawa ng PreviewProvider

Mga praktikal na halimbawa ay nagpapakita ng iba’t ibang senaryo ng paggamit ng PreviewProvider: mula sa simpleng preview hanggang sa kumplikadong configuration na may live na data at UIKit compatibility.

Preview na may mock data

Mock data — ang karaniwang pattern para sa preview kapag ang View ay tumatanggap ng modelo. Sa halip na tunay na API, ang test data ay isinasalang-alang, na nagpapahintulot ng visual na pagsusuri ng UI state nang hindi pinapatakbo ang application.

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

UIKit preview sa pamamagitan ng UIViewRepresentable

UIKit compatibility — ang PreviewProvider ay gumagana rin sa mga UIKit component na nakabalot sa UIViewRepresentable. Ito ay nagpapahintulot ng preview ng mga umiiral na UIKit view sa SwiftUI Canvas nang walang pag-migrate ng buong proyekto.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // I-configure ang mapa
    }
}

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

PreviewProvider at SwiftUI Canvas

Canvas — ay ang visual editor ng Xcode na nagre-render ng resulta ng PreviewProvider sa real-time. Kung walang implementasyon ng PreviewProvider, nananatiling walang laman ang Canvas. Ang Canvas at PreviewProvider ay nagtutulungan: Tinutukoy ng PreviewProvider kung ano ang ipapakita, ang Canvas — kung saan at paano.

Mahalagang maunawaan: Canvas — ay ang kapaligiran ng pagpapatupad ng preview, hindi isang alternatibo sa PreviewProvider. Kahit na hindi buksan ng developer ang Canvas, ang PreviewProvider ay maaaring gamitin para sa mabilis na pagsusuri ng code sa pamamagitan ng preview na lumalabas kapag nag-hover sa icon ng Canvas. Ayon sa WWDC 2024, inirerekomenda ng Apple ang pagsulat ng PreviewProvider para sa bawat View bilang pamantayan ng pag-develop, katulad ng pagsulat ng unit test.

Rekomendasyon: sumulat ng PreviewProvider para sa bawat pampublikong View sa proyekto. Pinapabilis nito ang onboarding ng mga bagong developer, pinapasimple ang code review, at nagpapahintulot ng mabilis na pagsusuri ng visual na mga pagbabago nang hindi binubuo ang buong proyekto.

Mga karaniwang problema sa PreviewProvider

Problema 1: Hindi nag-a-update ang preview. Kung hindi ipinapakita ng Canvas ang mga pagbabago sa code, ang dahilan ay karaniwang ang DerivedData cache. Linisin ang DerivedData sa pamamagitan ng Product → Clean Build Folder (⇧⌘K) o manu-manong pagtanggal ng folder na ~/Library/Developer/Xcode/DerivedData. Pagkatapos ng paglilinis, muling itinatayo ng Canvas ang preview mula sa simula.

Problema 2: Hindi nakikita ng PreviewProvider ang @StateObject. Ang PreviewProvider ay lumilikha ng static na instance ng View, kaya ang mga dependency na nangangailangan ng injection (ViewModel, serbisyo) ay dapat ipasa sa pamamagitan ng initializer o @StateObject na may default na halaga. Gumamit ng mga mock object sa halip na tunay na serbisyo sa preview.

Problema 3: Hindi gumagana ang mga animation sa Canvas. Hindi sinusuportahan ng Canvas ang lahat ng SwiftUI animation — lalo na ang mga nakadepende sa oras (withAnimation na may pagkaantala, .spring). Para suriin ang mga animation, patakbuhin ang application sa simulator. Ang Canvas ay angkop para sa static na pagsusuri ng layout.

Pag-aayos ng PreviewProvider na may mga dependency

Injection ng dependency — ang pinakamahusay na paraan upang gumana ang PreviewProvider sa mga kumplikadong ViewModel. Gumawa ng hiwalay na instance ng ViewModel na may test data at ipasa ito sa initializer ng 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)
    }
}

Mock extensions: gumawa ng extension para sa ViewModel na nagbibigay ng mga static na .mock instance. Ito ay nagpapanatili ng test data malapit sa ViewModel at ginagawang nababasa ang PreviewProvider.