PreviewProvider — یہ کیا ہے، SwiftUI پروٹوکول اور Xcode میں ترتیب

PreviewProvider کیا ہے؟

PreviewProvider ایک SwiftUI پروٹوکول ہے جو Xcode Canvas میں پیش نظارہ مواد بنانے کے لیے معاہدے کی وضاحت کرتا ہے۔ پروٹوکول میں ایک لازمی خاصیت ہے: previews قسم some View کی۔ previews کے ذریعے لوٹائی گئی کوئی بھی قدر Canvas میں انٹرایکٹو پیش نظارہ کے طور پر ظاہر ہوتی ہے۔ PreviewProvider کو وراثت کی ضرورت نہیں ہے — extension میں جامد نفاذ کافی ہے۔

فن تعمیر کے لحاظ سے، PreviewProvider SwiftUI رن ٹائم کا حصہ نہیں ہے — یہ خالصتاً ایک ڈویلپمنٹ ٹول ہے۔ پروٹوکول @available(iOS 13.0, *) وصف سے نشان زد ہے اور ریلیز بلڈ میں مرتب نہیں ہوتا، کیونکہ Xcode مشروط تالیف کا استعمال کرتا ہے تاکہ پیش نظارہ کوڈ کو پروڈکشن سے خارج کیا جا سکے۔ اس کا مطلب ہے کہ PreviewProvider بائنری سائز یا ایپلیکیشن کارکردگی کو متاثر نہیں کرتا۔

previews پروٹوکول

previews خاصیت PreviewProvider کی واحد ضرورت ہے۔ اسے کوئی بھی View لوٹانا چاہیے: سادہ Text سے لے کر Group اور ForEach کے ساتھ پیچیدہ درجہ بندی تک۔ Xcode لوٹائی گئی View کو Canvas میں رینڈر کرتا ہے، سسٹم سیٹنگز (تھیم، سائز، فونٹ) لاگو کرتا ہے۔

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

نام رکھنے کا طریقہ: Apple پیش نظارہ ساخت کا نام {ViewName}_Previews رکھنے کی سفارش کرتا ہے۔ یہ مرتب کرنے والے کے لیے ضروری نہیں ہے، لیکن پڑھنے کی اہلیت اور پروجیکٹ نیویگیشن کو بہتر بناتا ہے۔ Xcode نیا SwiftUI فائل بناتے وقت خود بخود یہ ٹیمپلیٹ داخل کرتا ہے۔

PreviewProvider کیسے کام کرتا ہے: پروٹوکول اور previews طریقہ

کام کرنے کا طریقہ کار PreviewProvider جامد تقسیم پر مبنی ہے: Xcode صرف Debug کنفیگریشن کے لیے PreviewProvider extension مرتب کرتا ہے اور Canvas کی تعمیر کے عمل کے دوران previews کو کال کرتا ہے۔ جب بھی کوڈ تبدیل ہوتا ہے، Xcode صرف تبدیل شدہ PreviewProvider کو دوبارہ مرتب کرتا ہے، تقریباً فوری پیش نظارہ اپ ڈیٹ کو یقینی بناتا ہے۔

SwiftUI سمیلیٹر یا ڈیوائس پر پیش نظارہ اور حتمی یوزر انٹرفیس کے درمیان صحیح مماثلت کی ضمانت نہیں دیتا — Canvas آسان رینڈرنگ استعمال کرتا ہے۔ تاخیر کے ساتھ اینیمیشن غلط ظاہر ہو سکتی ہیں، اور کچھ UIKit اجزاء (MapKit، WebView) اضافی ترتیب کے بغیر Canvas میں رینڈر نہیں ہوتے۔

Group کے ذریعے متعدد پیش نظارہ

Group ایک View کی متعدد حالتوں کو ایک ساتھ ظاہر کرنے کی اجازت دیتا ہے، مختلف کنفیگریشنز ترتیب دیتے وقت تکرار کو تیز کرتا ہے۔ Group کے اندر ہر پیش نظارہ آزادانہ طور پر رینڈر ہوتا ہے۔

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 میں ہر پیش نظارہ میں ایک لیبل شامل کرتا ہے، جو متعدد حالتوں کا موازنہ کرتے وقت خاص طور پر مفید ہے۔ Group میں پیش نظارہ کی زیادہ سے زیادہ تعداد محدود نہیں ہے، لیکن 6–8 سے زیادہ Canvas کو سست کر دیتے ہیں۔

Xcode میں پیش نظارہ کی ترتیب

Xcode فراہم کرتا ہے پیش نظارہ ڈسپلے کو ترتیب دینے کے لیے کئی ترمیم کار۔ اہم: previewDevice — کسی مخصوص ڈیوائس کی تقلید کرتا ہے (iPhone 16 Pro، iPad Air، Apple Watch Ultra)، previewLayout — سائز سیٹ کرتا ہے (device، fixed، sizeThatFits)۔ ان ترمیم کاروں کا مجموعہ پیش نظارہ ماحول پر مکمل کنٹرول دیتا ہے۔

previewDevice ڈیوائس کے نام کے ساتھ ایک سٹرنگ قبول کرتا ہے، مثال کے طور پر "iPhone 16 Pro" یا "iPad Pro 13-inch (M4)"۔ دستیاب ڈیوائسز کی فہرست Xcode میں انسٹال کردہ سمیلیٹر پر منحصر ہے۔ اگر ڈیوائس نہ ملی، Canvas بغیر کسی خرابی کے ڈیفالٹ ڈیوائس پر پیش نظارہ ظاہر کرتا ہے۔

مختلف ڈیوائسز کے لیے پیش نظارہ

عام عمل موافقت کی جانچ کرنے کے لیے ایک View کو ایک ساتھ متعدد ڈیوائسز پر دکھانا ہے۔ اس کے لیے ڈیوائس کے ناموں کی ایک صف کے ساتھ ForEach استعمال کیا جاتا ہے۔

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 کی مثالیں

عملی مثالیں سادہ پیش نظارہ سے لے کر لائیو ڈیٹا اور UIKit مطابقت کے ساتھ پیچیدہ کنفیگریشنز تک PreviewProvider کے استعمال کے مختلف منظرنامے دکھاتی ہیں۔

جعلی ڈیٹا کے ساتھ پیش نظارہ

جعلی ڈیٹا پیش نظارہ کے لیے ایک معیاری پیٹرن ہے جب View ایک ماڈل قبول کرتا ہے۔ اصل API کے بجائے، ٹیسٹ ڈیٹا استعمال کیا جاتا ہے، جو ایپلیکیشن شروع کیے بغیر UI حالت کی بصری تصدیق کی اجازت دیتا ہے۔

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 کے ذریعے UIKit پیش نظارہ

UIKit مطابقت — PreviewProvider UIViewRepresentable میں لپٹے UIKit اجزاء کے ساتھ بھی کام کرتا ہے۔ یہ پورے پروجیکٹ کو منتقل کیے بغیر SwiftUI Canvas میں موجودہ UIKit ویوز کا پیش نظارہ کرنے کی اجازت دیتا ہے۔

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 اور SwiftUI Canvas

Canvas Xcode کا بصری ایڈیٹر ہے جو PreviewProvider کے آؤٹ پٹ کو ریئل ٹائم میں رینڈر کرتا ہے۔ PreviewProvider کے نفاذ کے بغیر، Canvas خالی رہتا ہے۔ Canvas اور PreviewProvider جوڑی کے طور پر کام کرتے ہیں: PreviewProvider بتاتا ہے کہ کیا دکھانا ہے، Canvas بتاتا ہے کہ کہاں اور کیسے۔

یہ سمجھنا ضروری ہے: Canvas پیش نظارہ عملدرآمد کا ماحول ہے، PreviewProvider کا متبادل نہیں۔ یہاں تک کہ اگر ڈویلپر Canvas نہ کھولے، PreviewProvider Canvas آئیکن پر ہوور کرنے پر پاپ اپ پیش نظارہ کے ذریعے فوری کوڈ چیکنگ کے لیے استعمال کیا جا سکتا ہے۔ WWDC 2024 کے مطابق، Apple یونٹ ٹیسٹ لکھنے کی طرح، ہر View کے لیے PreviewProvider لکھنے کو ترقیاتی معیار کے طور پر تجویز کرتا ہے۔

سفارش: پروجیکٹ میں ہر عوامی View کے لیے PreviewProvider لکھیں۔ یہ نئے ڈویلپرز کے آن بورڈنگ کو تیز کرتا ہے، کوڈ کا جائزہ آسان بناتا ہے اور پورا پروجیکٹ بنائے بغیر بصری تبدیلیوں کی فوری تصدیق کی اجازت دیتا ہے۔

PreviewProvider کے ساتھ عام مسائل

مسئلہ 1: پیش نظارہ اپ ڈیٹ نہیں ہوتا۔ اگر Canvas کوڈ کی تبدیلیوں کو ظاہر نہیں کرتا، تو وجہ عام طور پر DerivedData کیش ہے۔ Product → Clean Build Folder (⇧⌘K) کے ذریعے DerivedData صاف کریں یا ~/Library/Developer/Xcode/DerivedData فولڈر کو دستی طور پر حذف کریں۔ صفائی کے بعد، Canvas پیش نظارہ کو نئے سرے سے بناتا ہے۔

مسئلہ 2: PreviewProvider @StateObject نہیں دیکھتا۔ PreviewProvider View کی ایک جامد مثال بناتا ہے، لہذا انجیکشن کی ضرورت والے انحصار (ViewModels، سروسز) کو ابتدا کار یا ڈیفالٹ ویلیو والے @StateObject کے ذریعے منتقل کیا جانا چاہیے۔ پیش نظارہ میں حقیقی خدمات کی بجائے جعلی اشیاء استعمال کریں۔

مسئلہ 3: Canvas میں اینیمیشن کام نہیں کرتیں۔ Canvas تمام SwiftUI اینیمیشن کو سپورٹ نہیں کرتا — خاص طور پر وہ جو وقت پر منحصر ہیں (تاخیر کے ساتھ withAnimation، .spring)۔ اینیمیشن کی جانچ کے لیے، ایپلیکیشن کو سمیلیٹر پر چلائیں۔ Canvas جامد لے آؤٹ کی تصدیق کے لیے موزوں ہے۔

انحصار کے ساتھ PreviewProvider کی اصلاح

انحصار انجیکشن پیچیدہ ViewModels کے ساتھ PreviewProvider کو کام کرنے کا بہترین طریقہ ہے۔ ٹیسٹ ڈیٹا کے ساتھ ایک علیحدہ ViewModel مثال بنائیں اور اسے 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)
    }
}

جعلی توسیعات: ViewModel کے لیے ایک extension بنائیں جو جامد .mock مثالیں فراہم کرے۔ یہ ٹیسٹ ڈیٹا کو ViewModel کے قریب رکھتا ہے اور PreviewProvider کو پڑھنے کے قابل بناتا ہے۔