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: من نص بسيط إلى تسلسل هرمي معقد مع 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. هذا ليس مطلبًا من المترجم، لكنه يُحسن readability والتنقل في المشروع. يقوم Xcode تلقائيًا بإدراج هذا القالب عند إنشاء ملف SwiftUI جديد.

كيف يعمل PreviewProvider: البروتوكول وطريقة previews

آلية العمل لـ PreviewProvider تعتمد على الإرسال الثابت: يقوم Xcode بتجميع extension الخاص بـ PreviewProvider فقط لتكوين Debug ويستدعي previews أثناء عملية بناء Canvas. في كل مرة يتغير فيها الكود، يعيد 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

أمثلة عملية تُظهر سيناريوهات استخدام متنوعة لـ PreviewProvider: من المعاينات البسيطة إلى التكوينات المعقدة مع بيانات حية والتوافق مع UIKit.

معاينة ببيانات وهمية

البيانات الوهمية هي نمط قياسي للمعاينات عندما تقبل View نموذجًا. بدلاً من API حقيقي، يتم استبدال بيانات اختبارية، مما يسمح بالتحقق البصري من حالة واجهة المستخدم دون تشغيل التطبيق.

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 عبر UIViewRepresentable

التوافق مع UIKit — يعمل PreviewProvider أيضًا مع مكونات UIKit المُغلّفة في UIViewRepresentable. هذا يسمح بمعاينة واجهات UIKit الحالية في SwiftUI Canvas دون ترحيل المشروع بأكمله.

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 بكتابة PreviewProvider لكل View كمعيار تطوير، مماثل لكتابة اختبارات الوحدة.

توصية: اكتب PreviewProvider لكل View عامة في المشروع. هذا يُسرّع onboarding المطورين الجدد، ويُبسّط مراجعة الكود، ويسمح بالتحقق السريع من التغييرات البصرية دون بناء المشروع بأكمله.

المشكلات الشائعة مع PreviewProvider

المشكلة 1: المعاينة لا تتحدّث. إذا كان Canvas لا يعكس تغييرات الكود، فالسبب غالبًا هو ذاكرة التخزين المؤقت DerivedData. نظّف DerivedData عبر Product → Clean Build Folder (⇧⌘K) أو بحذف المجلد ~/Library/Developer/Xcode/DerivedData يدويًا. بعد التنظيف، يعيد Canvas بناء المعاينة من الصفر.

المشكلة 2: PreviewProvider لا يرى @StateObject. يُنشئ PreviewProvider نسخة ثابتة من View، لذا يجب تمرير التبعيات التي تتطلب حقنًا (ViewModels، خدمات) عبر المُهيئ أو @StateObject بقيمة افتراضية. استخدم كائنات وهمية بدلاً من الخدمات الحقيقية في المعاينات.

المشكلة 3: الرسوم المتحركة لا تعمل في Canvas. لا يدعم Canvas جميع رسوم SwiftUI المتحركة — خاصة تلك التي تعتمد على التوقيت (withAnimation مع تأخير، .spring). لاختبار الرسوم المتحركة، شغّل التطبيق على محاكٍ. Canvas مناسب للتحقق الثابت من التصميم.

إصلاح PreviewProvider مع التبعيات

حقن التبعيات هو أفضل طريقة لجعل PreviewProvider يعمل مع ViewModels معقدة. أنشئ نسخة منفصلة من 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)
    }
}

امتدادات وهمية: أنشئ extension لـ ViewModel يُوفّر نسخ .mock ثابتة. هذا يُبقي بيانات الاختبار قريبة من ViewModel ويجعل PreviewProvider قابلًا للقراءة.