PreviewProvider — چیست، پروتکل SwiftUI و تنظیمات در Xcode

PreviewProvider چیست؟

PreviewProvider — پروتکل SwiftUI که قراردادی برای ایجاد محتوای پیش‌نمایش در Xcode Canvas تعریف می‌کند. پروتکل دارای یک ویژگی اجباری است: previews از نوع some View. هر مقداری که توسط previews برگردانده شود، در Canvas به عنوان یک پیش‌نمایش تعاملی نمایش داده می‌شود. PreviewProvider نیاز به ارث‌بری ندارد — یک پیاده‌سازی استاتیک در extension کافی است.

از نظر معماری، PreviewProvider بخشی از زمان اجرای SwiftUI نیست — این صرفاً یک ابزار توسعه است. پروتکل با ویژگی @available(iOS 13.0, *) مشخص شده و در بیلد release کامپایل نمی‌شود، زیرا Xcode از کامپایل شرطی برای حذف کد پیش‌نمایش از production استفاده می‌کند. این بدان معناست که PreviewProvider بر اندازه باینری و عملکرد برنامه تأثیر نمی‌گذارد.

پروتکل previews

ویژگی previews — تنها الزام PreviewProvider است. باید هر Viewای را برگرداند: از Text ساده تا سلسله‌مراتب پیچیده با Group و ForEach. Xcode View برگشتی را در Canvas با اعمال تنظیمات سیستم (تم، اندازه، فونت) رندر می‌کند.

import SwiftUI

struct GreetingView: View {
    let name: String
    
    var body: some View {
        Text("سلام، \(name)!")
            .padding()
    }
}

// PreviewProvider — پیاده‌سازی استاتیک
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

قرارداد نام‌گذاری: Apple توصیه می‌کند ساختار پیش‌نمایش را به صورت {ViewName}_Previews نام‌گذاری کنید. این یک الزام کامپایلر نیست، اما خوانایی و ناوبری در پروژه را بهبود می‌بخشد. Xcode هنگام ایجاد یک فایل SwiftUI جدید، این الگو را به طور خودکار جایگزین می‌کند.

PreviewProvider چگونه کار می‌کند: پروتکل و متد previews

مکانیسم کار PreviewProvider بر اساس ارسال استاتیک است: Xcode extension حاوی PreviewProvider را فقط برای پیکربندی Debug کامپایل می‌کند و previews را در فرآیند ساخت Canvas فراخوانی می‌کند. هر بار که کد تغییر می‌کند، Xcode فقط PreviewProviderهای تغییر یافته را دوباره کامپایل می‌کند که به‌روزرسانی تقریباً آنی پیش‌نمایش را تضمین می‌کند.

SwiftUI تطابق دقیق پیش‌نمایش با UI نهایی روی شبیه‌ساز یا دستگاه را تضمین نمی‌کند — 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 ارائه می‌دهد چندین modifier برای پیکربندی نمایش پیش‌نمایش. موارد اصلی: previewDevice — دستگاه خاصی را شبیه‌سازی می‌کند (iPhone 16 Pro، iPad Air، Apple Watch Ultra)، previewLayout — اندازه را تعیین می‌کند (device، fixed، sizeThatFits). ترکیب این modifierها کنترل کامل بر محیط پیش‌نمایش می‌دهد.

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 واقعی، داده‌های آزمایشی جایگزین می‌شوند که امکان بررسی بصری وضعیت 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")
    }
}

پیش‌نمایش UIKit از طریق UIViewRepresentable

سازگاری با UIKit — PreviewProvider با کامپوننت‌های UIKit که در UIViewRepresentable پیچیده شده‌اند نیز کار می‌کند. این امکان پیش‌نمایش Viewهای UIKit موجود در SwiftUI Canvas را بدون مهاجرت کل پروژه فراهم می‌کند.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // پیکربندی نقشه
    }
}

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 را به عنوان استاندارد توسعه، مشابه نوشتن تست‌های واحد توصیه می‌کند.

توصیه: برای هر View عمومی در پروژه PreviewProvider بنویسید. این کار سرعت راه‌اندازی توسعه‌دهندگان جدید را افزایش می‌دهد، بازبینی کد را ساده می‌کند و امکان بررسی سریع تغییرات بصری بدون ساخت کل پروژه را فراهم می‌کند.

مشکلات رایج با PreviewProvider

مشکل 1: پیش‌نمایش به‌روز نمی‌شود. اگر Canvas تغییرات کد را منعکس نمی‌کند، دلیل اغلب کش DerivedData است. DerivedData را از طریق Product → Clean Build Folder (⇧⌘K) یا با حذف دستی پوشه ~/Library/Developer/Xcode/DerivedData پاک کنید. پس از پاک‌سازی، Canvas پیش‌نمایش را از نو می‌سازد.

مشکل 2: PreviewProvider @StateObject را نمی‌بیند. PreviewProvider یک نمونه استاتیک از View ایجاد می‌کند، بنابراین وابستگی‌هایی که نیاز به تزریق دارند (ViewModel، سرویس‌ها) باید از طریق init یا @StateObject با مقدار پیش‌فرض منتقل شوند. در پیش‌نمایش به جای سرویس‌های واقعی از اشیاء ساختگی استفاده کنید.

مشکل 3: انیمیشن‌ها در Canvas کار نمی‌کنند. Canvas از همه انیمیشن‌های SwiftUI پشتیبانی نمی‌کند — به ویژه آنهایی که به زمان وابسته هستند (withAnimation با تأخیر، .spring). برای بررسی انیمیشن‌ها برنامه را روی شبیه‌ساز اجرا کنید. Canvas برای بررسی استاتیک layout مناسب است.

رفع PreviewProvider با وابستگی‌ها

تزریق وابستگی — بهترین راه برای کار کردن PreviewProvider با ViewModelهای پیچیده. یک نمونه جداگانه از ViewModel با داده‌های آزمایشی ایجاد کنید و آن را به init ویو منتقل کنید.

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 را خوانا می‌کند.