Property Wrapper: ключови понятия, синтаксис и примери в SwiftUI

Какво е Property Wrapper?

Property Wrapper е езикова конструкция на Swift, появила се във версия 5.1, която позволява капсулиране на логиката за достъп до свойство в отделен тип. Вместо да пишат повтарящи се getter и setter във всеки клас, разработчикът декларира обвивката веднъж и я прилага чрез анотация @ преди типа. Swift автоматично обвива свойството в указания тип, извиквайки неговите методи wrappedValue и projectedValue при четене и запис. Според Apple (WWDC 2019), Property Wrappers се превърнаха в ключова абстракция за SwiftUI.

Обвивката на свойство е структура или клас с атрибут @propertyWrapper. Вътре такъв тип трябва да имплементира свойството wrappedValue, което връща и задава актуалната стойност. Компилаторът на Swift заменя препратките към оригиналното свойство с извиквания на wrappedValue, напълно скривайки имплементацията от извикващия код. Допълнително може да се дефинира projectedValue — проекция, достъпна чрез символа $.

Предимството на Property Wrappers се състои в многократното използване на логика. Например може да се създаде обвивка за валидация на имейл, кеширане на стойности или синхронизация с хранилище — и да се приложи към всяко свойство в проекта. В SwiftUI тази концепция се използва навсякъде: всеки механизъм за управление на състояние е имплементиран като отделен Property Wrapper.

Как работи Property Wrapper в Swift?

При деклариране на свойство с анотация @WrapperType var value: T компилаторът на Swift трансформира кода. Той създава инстанция на WrapperType и генерира достъп до свойството чрез wrappedValue. Изходният код let x = value се превръща в let x = _value.wrappedValue, а value = newValue — в _value.wrappedValue = newValue. Тази трансформация се случва на етап компилация, без runtime натоварване.

@propertyWrapper
struct Capitalized {
    private var text: String

    var wrappedValue: String {
        get { text }
        set { text = newValue.capitalized }
    }

    init(initialValue: String) {
        text = initialValue.capitalized
    }
}

В листинга е показана обвивка Capitalized, която автоматично форматира текст с главна буква. При присвояване на стойност сетърът извиква capitalized преди запазване. Сега всяко свойство с анотация @Capitalized ще съхранява само коректно форматиран текст. Този подход напълно елиминира дублирането на код за валидация и форматиране.

Проекцията (projectedValue) — допълнителен комуникационен канал, достъпен чрез префикс $. В SwiftUI тази възможност се използва навсякъде: $state предоставя Binding, а $observedObject връща Published.Publisher. Проекцията позволява на обвивката да предостави разширен интерфейс без промяна на основния достъп до стойността.

Основни Property Wrappers в SwiftUI

SwiftUI включва пет вградени Property Wrappers за управление на състояние: @State, @Binding, @ObservedObject, @StateObject и @Environment. Всеки от тях решава конкретна задача и се използва в различни сценарии. @State е предназначен за прости локални данни, @Binding — за предаване на препратка към данни в дъщерни изгледи, @ObservedObject и @StateObject — за сложни обекти, @Environment — за системни стойности от йерархията.

Изборът на конкретен Property Wrapper зависи от източника на данни и техния жизнен цикъл. Ако данните принадлежат на един изглед и не са необходими на дъщерни компоненти — използвайте @State. Ако дъщерният изглед трябва да променя данните на родителя — приложете @Binding. За обекти, използвани в няколко изгледа, са подходящи @ObservedObject и @StateObject.

@State: локално състояние на изглед

@State е Property Wrapper за съхраняване на локално състояние в рамките на един изглед. SwiftUI автоматично управлява паметта за @State свойства и прерисува изгледа при всяка промяна. @State е подходящ за прости типове (String, Int, Bool, enum) и структури, които принадлежат изключително на текущия изглед. При промяна на стойността SwiftUI повторно изпълнява свойството body.

struct CounterView: View {
    @State private var count: Int = 0

    var body: some View {
        VStack {
            Text("Брой: \(count)")
            Button("Увеличи") {
                count += 1
            }
        }
    }
}

В примера @State свойството count съхранява текущата стойност на брояча. SwiftUI създава област за съхранение за това свойство в купа и я свързва с жизнения цикъл на CounterView. При натискане на бутона count се увеличава с 1, SwiftUI открива промяната и повторно изпълнява body, показвайки новата стойност. Важно: @State не трябва да се използва за сложни референтни типове — за това са предназначени @StateObject и @ObservedObject.

@Binding: двупосочна връзка между изгледи

@Binding създава препратка към източник на данни, принадлежащ на друг изглед. Binding не съхранява стойността самостоятелно — той чете и записва данни чрез @State, @StateObject или друг Binding, предаден от родителя. Това позволява на дъщерни компоненти да променят състоянието на предшественика без пряко притежание на данните и без callback-и.

struct ToggleSwitch: View {
    @Binding var isOn: Bool

    var body: some View {
        Toggle("Switch", isOn: $isOn)
    }
}

В листинга ToggleSwitch получава @BindingBool от родителския изглед. Родителят създава @State var isToggleOn = false и предава $isToggleOn на инициализатора на ToggleSwitch. Когато потребителят превключи Toggle в рамките на дъщерния изглед, промяната незабавно се отразява в родителския @State. Механизмът Binding напълно елиминира необходимостта от делегати или затваряния за предаване на промени нагоре по йерархията.

@ObservedObject и @StateObject: външни данни

@ObservedObject е Property Wrapper за наблюдение на инстанция на ObservableObject, предадена отвън. Изгледът не притежава този обект — той се създава в родителския компонент или се инжектира чрез Environment. Когато някое @Published свойство вътре в ObservableObject се промени, SwiftUI прерисува всички изгледи, абонирани чрез @ObservedObject.

@StateObject е обвивка за създаване и притежание на ObservableObject директно в изгледа. За разлика от @ObservedObject, @StateObject гарантира единствена инстанция на обекта през целия жизнен цикъл на изгледа. Дори ако SwiftUI пресъздаде структурата на изгледа (което се случва често), @StateObject запазва съществуващия обект и не извиква повторно инициализатора.

class UserSettings: ObservableObject {
    @Published var username: String = "Guest"
}

struct ProfileView: View {
    @StateObject var settings = UserSettings()

    var body: some View {
        ChildProfileView(settings: settings)
    }
}

struct ChildProfileView: View {
    @ObservedObject var settings: UserSettings

    var body: some View {
        Text("Здравейте, \(settings.username)")
    }
}

В примера ProfileView създава UserSettings чрез @StateObject, ставайки собственик на обекта. ChildProfileView получава същата инстанция чрез @ObservedObject — наблюдава, но не управлява жизнения цикъл. При промяна на username и двата изгледа се актуализират. Ако ChildProfileView използваше @StateObject вместо @ObservedObject, при всяко рендиране щеше да се създава нова инстанция с начална стойност.

Ключово правило: @StateObject се прилага в изгледа, който създава обекта (източник на истина), а @ObservedObject — в изгледа, който получава готовия обект от родителя. Нарушаването на това правило води до загуба на състояние или неочаквано пресъздаване на данни.

Създаване на собствен Property Wrapper

Swift позволява създаване на персонализирани Property Wrappers за всяка повтаряща се логика за достъп до свойства. Достатъчно е да декларирате структура или клас с атрибут @propertyWrapper и да имплементирате wrappedValue. По-долу е показана обвивката UserDefaultsWrapper, която автоматично синхронизира стойността с UserDefaults.

@propertyWrapper
struct UserDefaultsWrapper<T> {
    let key: String
    let defaultValue: T

    var wrappedValue: T {
        get { UserDefaults.standard.object(forKey: key) as? T ?? defaultValue }
        set { UserDefaults.standard.set(newValue, forKey: key) }
    }
}

struct AppConfig {
    @UserDefaultsWrapper(key: "theme", defaultValue: "light")
    var theme: String
}

Обвивката UserDefaultsWrapper използва generic T за работа с произволен тип данни, поддържан от UserDefaults. Getter-ът чете стойността по ключ, setter-ът записва. Прилагането на @UserDefaultsWrapper(key:defaultValue:) към свойството theme автоматично го свързва с хранилището — цялата логика за работа с UserDefaults е скрита вътре в обвивката. Това е типичен пример за намаляване на boilerplate код с помощта на Property Wrappers.

При създаване на персонализирани обвивки е важно да се вземе предвид производителността. Тъй като getter и setter се извикват при всеки достъп до свойството, не трябва да се поставят тежки I/O операции в wrappedValue. За асинхронно съхранение на данни е по-добре да се комбинират Property Wrappers с ObservableObject и @Published.