Property Wrapper: mga pangunahing konsepto, syntax at halimbawa sa SwiftUI

Ano ang Property Wrapper?

Property Wrapper ay isang konstruksyon ng wika ng Swift na lumitaw sa bersyon 5.1, na nagbibigay-daan sa pag-encapsulate ng lohika ng pag-access sa property sa isang hiwalay na uri. Sa halip na magsulat ng paulit-ulit na getter at setter sa bawat klase, ang developer ay nagdedeklara ng wrapper nang isang beses at inilalapat ito sa pamamagitan ng @ annotation bago ang uri. Awtomatikong binabalot ng Swift ang property sa tinukoy na uri, na tinatawag ang mga pamamaraan nitong wrappedValue at projectedValue sa pagbasa at pagsulat. Ayon sa Apple (WWDC 2019), ang Property Wrappers ay naging pangunahing abstraction para sa SwiftUI.

Ang wrapper ng property ay isang structure o class na may attribute na @propertyWrapper. Sa loob, ang ganitong uri ay dapat magpatupad ng property na wrappedValue na nagbabalik at nagtatakda ng kasalukuyang halaga. Pinapalitan ng Swift compiler ang mga referensya sa orihinal na property ng mga tawag sa wrappedValue, ganap na itinatago ang implementasyon mula sa tumatawag na code. Bukod pa rito, maaaring tukuyin ang projectedValue — isang proyeksyon na naa-access sa pamamagitan ng simbolong $.

Ang bentahe ng Property Wrappers ay nakasalalay sa muling paggamit ng lohika. Halimbawa, maaaring gumawa ng wrapper para sa validation ng email, pag-cache ng mga halaga, o pag-sync sa storage — at ilapat ito sa anumang property sa proyekto. Sa SwiftUI, ang konseptong ito ay ginagamit sa lahat ng dako: bawat mekanismo ng pamamahala ng estado ay ipinatupad bilang isang hiwalay na Property Wrapper.

Paano gumagana ang Property Wrapper sa Swift?

Sa pagdedeklara ng property na may annotation na @WrapperType var value: T, binabago ng Swift compiler ang code. Gumagawa ito ng instance ng WrapperType at bumubuo ng access sa property sa pamamagitan ng wrappedValue. Ang source code na let x = value ay nagiging let x = _value.wrappedValue, at ang value = newValue ay nagiging _value.wrappedValue = newValue. Ang pagbabagong ito ay nangyayari sa yugto ng compilation, nang walang runtime overhead.

@propertyWrapper
struct Capitalized {
    private var text: String

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

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

Sa listing ay ipinakita ang wrapper na Capitalized, na awtomatikong nagfo-format ng text na may malaking titik. Sa pagtatalaga ng halaga, tinatawag ng setter ang capitalized bago mag-save. Ngayon ang anumang property na may annotation na @Capitalized ay mag-iimbak lamang ng tamang na-format na text. Ang pamamaraang ito ay ganap na nag-aalis ng pagdodoble ng validation at formatting code.

Ang proyeksyon (projectedValue) — isang karagdagang channel ng komunikasyon, naa-access sa pamamagitan ng prefix na $. Sa SwiftUI, ang kakayahang ito ay ginagamit sa lahat ng dako: ang $state ay nagbibigay ng Binding, at ang $observedObject ay nagbabalik ng Published.Publisher. Ang proyeksyon ay nagpapahintulot sa wrapper na magbigay ng pinalawak na interface nang hindi binabago ang pangunahing access sa halaga.

Mga pangunahing Property Wrapper sa SwiftUI

Ang SwiftUI ay may kasamang limang built-in na Property Wrapper para sa pamamahala ng estado: @State, @Binding, @ObservedObject, @StateObject at @Environment. Ang bawat isa ay malulutas ang isang tiyak na gawain at ginagamit sa iba't ibang mga senaryo. Ang @State ay para sa simpleng lokal na data, @Binding — para sa pagpapasa ng referensya sa data sa mga child view, @ObservedObject at @StateObject — para sa mga kumplikadong object, @Environment — para sa mga halaga ng system mula sa hierarchy.

Ang pagpili ng isang tiyak na Property Wrapper ay depende sa pinagmulan ng data at sa kanilang lifecycle. Kung ang data ay pagmamay-ari ng isang view at hindi kailangan ng mga child component — gamitin ang @State. Kung ang child view ay kailangang baguhin ang data ng parent — ilapat ang @Binding. Para sa mga object na ginagamit sa maraming view, ang @ObservedObject at @StateObject ay angkop.

@State: lokal na estado ng view

@State ay isang Property Wrapper para sa pag-iimbak ng lokal na estado sa loob ng isang view. Awtomatikong pinamamahalaan ng SwiftUI ang memory para sa mga @State property at iginuhit muli ang view sa bawat pagbabago. Ang @State ay angkop para sa mga simpleng uri (String, Int, Bool, enum) at mga structure na eksklusibong pagmamay-ari ng kasalukuyang view. Sa pagbabago ng halaga, muling pinapatakbo ng SwiftUI ang property na body.

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

    var body: some View {
        VStack {
            Text("Bilang: \(count)")
            Button("Dagdagan") {
                count += 1
            }
        }
    }
}

Sa halimbawa, ang @State property na count ay nag-iimbak ng kasalukuyang halaga ng counter. Gumagawa ang SwiftUI ng storage area para sa property na ito sa heap at iniuugnay ito sa lifecycle ng CounterView. Sa pagpindot ng button, ang count ay tataas ng 1, nakikita ng SwiftUI ang pagbabago at muling pinapatakbo ang body, na nagpapakita ng bagong halaga. Mahalaga: Ang @State ay hindi dapat gamitin para sa mga kumplikadong referensyang uri — para dito ay ang @StateObject at @ObservedObject ang nilalayon.

@Binding: dalawang-direksyong koneksyon sa pagitan ng mga view

@Binding ay gumagawa ng referensya sa pinagmulan ng data na pagmamay-ari ng ibang view. Ang Binding ay hindi nag-iimbak ng halaga nang nakapag-iisa — ito ay nagbabasa at nagsusulat ng data sa pamamagitan ng @State, @StateObject o ibang Binding na ipinasa mula sa parent. Ito ay nagpapahintulot sa mga child component na baguhin ang estado ng ancestor nang walang direktang pagmamay-ari ng data at walang mga callback.

struct ToggleSwitch: View {
    @Binding var isOn: Bool

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

Sa listing, ang ToggleSwitch ay tumatanggap ng @BindingBool mula sa parent view. Ang parent ay gumagawa ng @State var isToggleOn = false at ipinapasa ang $isToggleOn sa initializer ng ToggleSwitch. Kapag inilipat ng user ang Toggle sa loob ng child view, ang pagbabago ay agad na sumasalamin sa @State ng parent. Ang mekanismo ng Binding ay ganap na nag-aalis ng pangangailangan para sa mga delegate o closure para sa pagpapasa ng mga pagbabago pataas sa hierarchy.

@ObservedObject at @StateObject: panlabas na data

@ObservedObject ay isang Property Wrapper para sa pagmamasid sa isang instance ng ObservableObject na ipinasa mula sa labas. Ang view ay hindi nagmamay-ari ng object na ito — ito ay nilikha sa parent component o ini-inject sa pamamagitan ng Environment. Kapag nagbago ang anumang @Published property sa loob ng ObservableObject, iginuhit muli ng SwiftUI ang lahat ng view na naka-subscribe sa pamamagitan ng @ObservedObject.

@StateObject ay isang wrapper para sa paglikha at pagmamay-ari ng ObservableObject nang direkta sa view. Hindi tulad ng @ObservedObject, ginagarantiya ng @StateObject ang nag-iisang instance ng object sa buong lifecycle ng view. Kahit na muling likhain ng SwiftUI ang structure ng view (na madalas mangyari), pinapanatili ng @StateObject ang umiiral na object at hindi na muling tinatawag ang initializer.

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

Sa halimbawa, ang ProfileView ay gumagawa ng UserSettings sa pamamagitan ng @StateObject, na nagiging may-ari ng object. Ang ChildProfileView ay tumatanggap ng parehong instance sa pamamagitan ng @ObservedObject — nagmamasid, ngunit hindi pinamamahalaan ang lifecycle. Kapag nagbago ang username, ang parehong view ay naa-update. Kung ang ChildProfileView ay gumamit ng @StateObject sa halip na @ObservedObject, sa bawat pag-render ay gagawa ng bagong instance na may paunang halaga.

Ang pangunahing patakaran: Ang @StateObject ay inilalapat sa view na lumikha ng object (pinagmulan ng katotohanan), at ang @ObservedObject ay sa view na tumatanggap ng handa na object mula sa parent. Ang paglabag sa patakarang ito ay humahantong sa pagkawala ng estado o hindi inaasahang muling paglikha ng data.

Paggawa ng sariling Property Wrapper

Pinapayagan ng Swift ang paggawa ng mga custom na Property Wrapper para sa anumang paulit-ulit na lohika ng pag-access sa property. Sapat na magdeklara ng isang structure o class na may attribute na @propertyWrapper at ipatupad ang wrappedValue. Sa ibaba ay ipinakita ang wrapper na UserDefaultsWrapper, na awtomatikong nag-sync ng halaga sa 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
}

Ang wrapper na UserDefaultsWrapper ay gumagamit ng generic T upang gumana sa anumang uri ng data na sinusuportahan ng UserDefaults. Ang getter ay nagbabasa ng halaga ayon sa key, ang setter ay nagsusulat. Ang paglalapat ng @UserDefaultsWrapper(key:defaultValue:) sa property na theme ay awtomatikong nag-uugnay nito sa storage — lahat ng lohika ng pagtatrabaho sa UserDefaults ay nakatago sa loob ng wrapper. Ito ay isang tipikal na halimbawa ng pagbawas ng boilerplate code gamit ang Property Wrappers.

Sa paggawa ng mga custom na wrapper, mahalagang isaalang-alang ang performance. Dahil ang getter at setter ay tinatawag sa bawat pag-access sa property, hindi dapat ilagay ang mabibigat na I/O operation sa wrappedValue. Para sa asynchronous na pag-iimbak ng data, mas mahusay na pagsamahin ang Property Wrappers sa ObservableObject at @Published.