@ViewBuilder: چیست، result builder برای View در SwiftUI

@ViewBuilder در SwiftUI چیست؟

@ViewBuilder — یک حاشیه‌نویسی است که الگوی result builder (SE-0289) را پیاده‌سازی می‌کند و به SwiftUI اجازه می‌دهد چندین View را با استفاده از نحو اعلامی در یک ترکیب جمع کند. این حاشیه‌نویسی به طور خودکار عبارات متعدد، ساختارهای شرطی و مقادیر اختیاری را در انواع مربوطه می‌پیچد: TupleView، ConditionalContent، OptionalContent.

پیش از ظهور result builder، توسعه‌دهندگان مجبور بودند عناصر را به صورت دستی در VStack یا HStack بپیچند و برای منطق شرطی از عملگرهای سه‌تایی یا روش‌های کارخانه‌ای استفاده کنند. @ViewBuilder نحو SwiftUI را مختصر و خوانا کرد و امکان نوشتن کدی را فراهم کرد که مانند Swift معمولی با if/else و حلقه‌ها به نظر می‌رسد.

بر اساس Swift Evolution SE-0289، result builders یک مکانیزم عمومی هستند که به SwiftUI محدود نمی‌شوند. @ViewBuilder یکی از پیاده‌سازی‌های این مکانیزم است، در کنار @StringBuilder برای ساخت رشته‌ها و پیاده‌سازی‌های کتابخانه‌ای برای DSLهای دیگر. در SwiftUI از @ViewBuilder نه تنها برای body، بلکه برای پارامترهای بسته‌کننده کانتینرها نیز استفاده می‌شود (VStack، HStack، ZStack، List).

تفاوت با رویکرد امری

در UIKit امری، شما به صورت امری UIView ایجاد می‌کنید، ویژگی‌های آن را پیکربندی می‌کنید و از طریق addSubview به سلسله‌مراتب اضافه می‌کنید. در SwiftUI با @ViewBuilder، شما به صورت اعلامی توصیف می‌کنید که کدام Viewها باید نمایش داده شوند و SwiftUI خود ایجاد، به‌روزرسانی و حذف عناصر را بر اساس تغییرات حالت مدیریت می‌کند.

@ViewBuilder چگونه کار می‌کند: result builder

Result builder — مکانیزم Swift است که دنباله‌ای از عبارات را از طریق متدهای استاتیک buildBlock، buildOptional، buildEither و دیگران به یک مقدار ترکیبی تبدیل می‌کند. وقتی کامپایلر حاشیه‌نویسی @ViewBuilder را می‌بیند، به طور خودکار این متدها را در فرآیند کامپایل بر بلوک کد اعمال می‌کند.

@resultBuilder
struct ViewBuilder {
    static func buildBlock<C0, C1>(_ c0: C0, _ c1: C1) -> TupleView<(C0, C1)>
    static func buildIf<C>(_ c: C?) -> C?
    static func buildEither<T, F>(first: T) -> ConditionalContent<T, F>
    static func buildEither<T, F>(second: F) -> ConditionalContent<T, F>
}

buildBlock از ۱ تا ۱۰ عبارت دریافت می‌کند و TupleView برمی‌گرداند. هر تعداد عبارت overload مخصوص buildBlock خود را دارد: از buildBlock<C0> تا buildBlock<C0, C1, ..., C9>. به همین دلیل تعداد عناصر در یک بلوک @ViewBuilder به ۱۰ محدود شده است.

buildEither (first/second) ساختارهای if/else را پردازش می‌کند. هر شاخه به متد مربوطه ارسال می‌شود و نتیجه در ConditionalContent پیچیده می‌شود — نوعی که انواع خاص شاخه‌ها را پنهان می‌کند و یک رابط یکپارچه برای SwiftUI فراهم می‌کند.

کار ضمنی @ViewBuilder

در SwiftUI، ویژگی body به طور ضمنی با @ViewBuilder حاشیه‌نویسی شده است — شما این حاشیه‌نویسی را در کد نمی‌بینید، اما کامپایلر آن را به طور خودکار اعمال می‌کند. با این حال، برای ویژگی‌های سفارشی که چندین View برمی‌گردانند یا پارامترهای بسته‌کننده، حاشیه‌نویسی باید به صراحت مشخص شود.

محدودیت‌های @ViewBuilder و نحوه دور زدن آنها

محدودیت ۱ — ۱۰ عنصر در یک بلوک. این معروف‌ترین محدودیت @ViewBuilder است. اگر نیاز به نمایش بیش از ۱۰ عنصر در یک سطح دارید، کامپایلر خطا می‌دهد. می‌توانید با Group، ForEach، List یا تقسیم به زیرکامپوننت‌ها این محدودیت را دور بزنید. Group تودرتویی بصری اضافه نمی‌کند، اما هر Group یک عنصر محسوب می‌شود.

struct ManyElementsView: View {
    var body: some View {
        Group {
            Text("1"); Text("2"); Text("3")
            Text("4"); Text("5"); Text("6")
            Text("7"); Text("8"); Text("9")
        }
        Group {
            Text("10"); Text("11"); Text("12")
        }
    }
}

محدودیت ۲ — عدم پشتیبانی از برخی ساختارها. @ViewBuilder از do/catch، guard، for-in (بدون ForEach) و سایر ساختارهای کنترلی پشتیبانی نمی‌کند. برای حلقه‌ها از ForEach با داده‌های قابل شناسایی استفاده کنید. برای مدیریت خطا از Viewهای جداگانه‌ای استفاده کنید که Result یا مقادیر اختیاری دریافت می‌کنند.

محدودیت ۳ — دشواری اشکال‌زدایی. در صورت خطا در @ViewBuilder، کامپایلر پیام‌های طولانی و مبهمی تولید می‌کند که یافتن علت اصلی در آنها دشوار است. مشکلات رایج: عدم تطابق نوع در شاخه‌های if/else، تجاوز از محدودیت ۱۰ عنصر یا عدم وجود overload مورد نیاز buildBlock.

الگوهای استفاده از @ViewBuilder

الگوی ۱: نمایش شرطی با if/else. رایج‌ترین سناریوی استفاده از @ViewBuilder. امکان نمایش Viewهای مختلف بسته به وضعیت بدون استفاده از عملگرهای سه‌تایی یا روش‌های کارخانه‌ای.

struct StatusView: View {
    var status: LoadStatus

    @ViewBuilder
    var body: some View {
        switch status {
        case .loading:
            ProgressView("Loading...")
        case .loaded(let data):
            DataView(data: data)
        case .error(let message):
            ErrorView(message: message)
        }
    }
}

الگوی ۲: @ViewBuilder در پارامترهای توابع و مقداردهنده‌ها. برای ایجاد کانتینرهای قابل استفاده مجدد که Viewهای فرزند را از طریق بسته دریافت می‌کنند. این الگوی استاندارد برای کتابخانه‌ها و کامپوننت‌های UI است.

struct SectionCard<Content: View>: View {
    let title: String
    @ViewBuilder let content: Content

    var body: some View {
        VStack(alignment: .leading) {
            Text(title).font(.headline)
            content
        }
        .padding()
        .background(Color.gray.opacity(0.1))
        .cornerRadius(12)
    }
}

الگوی ۳: ترکیب با ForEach. @ViewBuilder به درستی با ForEach کار می‌کند و امکان تولید پویای عناصر از آرایه داده را فراهم می‌کند. هر عنصر ForEach در زمینه @ViewBuilder یک عبارت محسوب می‌شود.

ایجاد ViewBuilder سفارشی برای کامپوننت‌های قابل استفاده مجدد

ViewBuilder سفارشی — یک تابع یا ویژگی کاربر است که با @ViewBuilder حاشیه‌نویسی شده و some View برمی‌گرداند. چنین توابعی امکان کپسوله‌سازی منطق نمایش پیچیده و استفاده مجدد از آن در بخش‌های مختلف برنامه را فراهم می‌کنند.

struct FormRow<Content: View>: View {
    let label: String
    @ViewBuilder let content: Content

    var body: some View {
        HStack {
            Text(label)
                .frame(width: 120, alignment: .trailing)
            content
        }
    }
}

// استفاده:
FormRow(label: "Name") {
    TextField("Enter name", text: $name)
}

FormRow(label: "Gender") {
    Picker("Select", selection: $gender) {
        Text("مرد").tag(Gender.male)
        Text("زن").tag(Gender.female)
    }
}

قاعده مهم: تابع سفارشی با @ViewBuilder باید some View برگرداند، نه یک نوع خاص یا پروتکل View. فقط نوع opaque امکان پنهان کردن پیاده‌سازی خاص و حفظ انعطاف‌پذیری ترکیب را فراهم می‌کند.

عملکرد: توابع سفارشی @ViewBuilder در مقایسه با کد مستقیم در body سربار اضافی ندارند. کامپایلر فراخوانی‌ها را inline می‌کند و کد حاصل را بهینه می‌سازد. تقسیم body به توابع @ViewBuilder خوانایی را بدون کاهش عملکرد بهبود می‌بخشد.