Property Wrapper: kulcsfogalmak, szintaxis és példák a SwiftUI-ban

Mi az a Property Wrapper?

Property Wrapper egy Swift nyelvi konstrukció, amely az 5.1-es verzióban jelent meg, és lehetővé teszi a tulajdonságelérés logikájának egy külön típusba való beágyazását. Ahelyett, hogy minden osztályban ismétlődő gettereket és settereket írna, a fejlesztő egyszer deklarálja a burkolót, és a @ annotáción keresztül alkalmazza a típus előtt. A Swift automatikusan becsomagolja a tulajdonságot a megadott típusba, és olvasáskor/íráskor meghívja annak wrappedValue és projectedValue metódusait. Az Apple (WWDC 2019) szerint a Property Wrapperek a SwiftUI kulcsfontosságú absztrakciójává váltak.

A tulajdonságburkoló egy struktúra vagy osztály a @propertyWrapper attribútummal. Belül az ilyen típusnak meg kell valósítania a wrappedValue tulajdonságot, amely visszaadja és beállítja az aktuális értéket. A Swift fordító az eredeti tulajdonságra való hivatkozásokat wrappedValue hívásokkal helyettesíti, teljesen elrejtve a megvalósítást a hívó kód elől. Ezenkívül definiálható a projectedValue — egy projekció, amely a $ szimbólumon keresztül érhető el.

A Property Wrapperek előnye a logika újrafelhasználásában rejlik. Például létrehozható burkoló e-mail validáláshoz, értékek gyorsítótárazásához vagy tárolóval való szinkronizáláshoz — és alkalmazható bármely tulajdonságra a projektben. A SwiftUI-ban ez a koncepció mindenhol használatos: az állapotkezelés minden mechanizmusa külön Property Wrapperként van megvalósítva.

Hogyan működik a Property Wrapper Swift-ben?

Egy tulajdonság @WrapperType var value: T annotációval történő deklarálásakor a Swift fordító átalakítja a kódot. Létrehoz egy WrapperType példányt, és a tulajdonsághoz való hozzáférést a wrappedValue-n keresztül generálja. A let x = value forráskód let x = _value.wrappedValue-vé, a value = newValue pedig _value.wrappedValue = newValue-vé alakul. Ez az átalakítás fordítási időben történik, futásidejű többletterhelés nélkül.

@propertyWrapper
struct Capitalized {
    private var text: String

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

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

A listában a Capitalized burkoló látható, amely automatikusan nagybetűvel formázza a szöveget. Érték hozzárendelésekor a setter a mentés előtt meghívja a capitalized-et. Mostantól bármely @Capitalized annotációval ellátott tulajdonság csak helyesen formázott szöveget tárol. Ez a megközelítés teljesen kiküszöböli az validációs és formázási kód ismétlődését.

A projekció (projectedValue) — egy további kommunikációs csatorna, amely a $ előtaggal érhető el. A SwiftUI-ban ez a képesség mindenhol használatos: a $state Binding-t ad, a $observedObject pedig Published.Publisher-t ad vissza. A projekció lehetővé teszi a burkoló számára, hogy kiterjesztett interfészt biztosítson anélkül, hogy megváltoztatná az értékhez való alaphozzáférést.

Fő Property Wrapperek a SwiftUI-ban

A SwiftUI öt beépített Property Wrappert tartalmaz az állapotkezeléshez: @State, @Binding, @ObservedObject, @StateObject és @Environment. Mindegyik egy adott feladatot old meg, és különböző forgatókönyvekben használatos. A @State egyszerű helyi adatokhoz, a @Binding — adatok referenciájának gyermek nézetekbe való átadásához, a @ObservedObject és @StateObject — összetett objektumokhoz, a @Environment — rendszerértékekhez a hierarchiából.

Egy adott Property Wrapper kiválasztása az adatforrástól és azok életciklusától függ. Ha az adatok egy nézethez tartoznak, és nem szükségesek gyermek komponensek számára — használja a @State-t. Ha a gyermek nézetnek módosítania kell a szülő adatait — alkalmazza a @Binding-t. Több nézetben használt objektumokhoz a @ObservedObject és @StateObject megfelelő.

@State: a nézet lokális állapota

@State egy Property Wrapper a lokális állapot tárolására egy nézeten belül. A SwiftUI automatikusan kezeli a memóriát a @State tulajdonságokhoz, és minden változásnál újrarajzolja a nézetet. A @State egyszerű típusokhoz (String, Int, Bool, enum) és struktúrákhoz alkalmas, amelyek kizárólag az aktuális nézethez tartoznak. Az érték változásakor a SwiftUI újra futtatja a body tulajdonságot.

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

    var body: some View {
        VStack {
            Text("Szám: \(count)")
            Button("Növelés") {
                count += 1
            }
        }
    }
}

A példában a @State tulajdonság count tárolja a számláló aktuális értékét. A SwiftUI tárolóterületet hoz létre ehhez a tulajdonsághoz a heap-en, és összekapcsolja a CounterView életciklusával. A gomb megnyomásakor a count 1-gyel nő, a SwiftUI érzékeli a változást, és újra futtatja a body-t, megjelenítve az új értéket. Fontos: a @State nem használható összetett referencia típusokhoz — erre a @StateObject és @ObservedObject szolgál.

@Binding: kétirányú kapcsolat nézetek között

@Binding referenciát hoz létre egy másik nézethez tartozó adatforráshoz. A Binding nem tárolja az értéket önállóan — a @State, @StateObject vagy más, a szülőtől átadott Binding segítségével olvassa és írja az adatokat. Ez lehetővé teszi a gyermek komponensek számára, hogy az ős állapotát közvetlen adattulajdonlás és callback-ek nélkül módosítsák.

struct ToggleSwitch: View {
    @Binding var isOn: Bool

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

A listában a ToggleSwitch egy @BindingBool-t kap a szülő nézettől. A szülő létrehozza a @State var isToggleOn = false-t, és átadja a $isToggleOn-t a ToggleSwitch inicializátorának. Amikor a felhasználó átkapcsolja a Toggle-t a gyermek nézeten belül, a változás azonnal tükröződik a szülő @State-jében. A Binding mechanizmus teljesen kiküszöböli a delegate-ek vagy closure-ok szükségességét a változások hierarchiában felfelé történő továbbításához.

@ObservedObject és @StateObject: külső adatok

@ObservedObject egy Property Wrapper a kívülről átadott ObservableObject példány megfigyelésére. A nézet nem tulajdonosa ennek az objektumnak — az a szülő komponensben jön létre, vagy Environment-en keresztül injektálódik. Amikor bármely @Published tulajdonság megváltozik az ObservableObject-en belül, a SwiftUI újrarajzolja az összes, @ObservedObject-en keresztül feliratkozott nézetet.

@StateObject egy burkoló az ObservableObject közvetlen létrehozására és tulajdonlására a nézetben. A @ObservedObject-tel ellentétben a @StateObject garantálja az objektum egyetlen példányát a nézet teljes életciklusa során. Még ha a SwiftUI újra létrehozza is a nézet struktúráját (ami gyakran előfordul), a @StateObject megtartja a meglévő objektumot, és nem hívja meg újra az inicializálót.

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("Szia, \(settings.username)")
    }
}

A példában a ProfileView a @StateObject segítségével hozza létre a UserSettings-t, ezzel az objektum tulajdonosává válva. A ChildProfileView ugyanazt a példányt kapja meg a @ObservedObject-en keresztül — megfigyeli, de nem kezeli az életciklust. Amikor a username megváltozik, mindkét nézet frissül. Ha a ChildProfileView a @ObservedObject helyett @StateObject-t használt volna, minden rendereléskor egy új példány jött volna létre a kezdeti értékkel.

A kulcsszabály: a @StateObject az objektumot létrehozó nézetben (az igazság forrásában) alkalmazandó, a @ObservedObject pedig abban a nézetben, amely a kész objektumot a szülőtől kapja. Ennek a szabálynak a megsértése állapotvesztéshez vagy az adatok váratlan újralétrehozásához vezet.

Saját Property Wrapper létrehozása

A Swift lehetővé teszi egyéni Property Wrapperek létrehozását bármilyen ismétlődő tulajdonságelérési logikához. Elég deklarálni egy struktúrát vagy osztályt a @propertyWrapper attribútummal, és megvalósítani a wrappedValue-t. Alább a UserDefaultsWrapper burkoló látható, amely automatikusan szinkronizálja az értéket a UserDefaults-szal.

@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
}

A UserDefaultsWrapper burkoló egy generic T-t használ a UserDefaults által támogatott bármely adattípussal való munkához. A getter kulcs alapján olvassa az értéket, a setter írja. A @UserDefaultsWrapper(key:defaultValue:) alkalmazása a theme tulajdonságra automatikusan összekapcsolja azt a tárolóval — a UserDefaults-szal való munka teljes logikája a burkolón belül van elrejtve. Ez tipikus példája a boilerplate kód Property Wrapperekkel történő csökkentésének.

Egyéni burkolók létrehozásakor fontos figyelembe venni a teljesítményt. Mivel a getter és setter minden tulajdonságeléréskor meghívódik, ne helyezzen nehéz I/O műveleteket a wrappedValue-ba. Aszinkron adattároláshoz jobb a Property Wrappereket ObservableObject-tel és @Published-del kombinálni.