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

Что такое Property Wrapper?

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

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

Преимущество Property Wrappers заключается в многократном использовании логики. Например, можно создать обёртку для валидации email, кэширования значений или синхронизации с хранилищем — и применять её к любому свойству в проекте. В 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 — для передачи ссылки на данные в дочерние view, @ObservedObject и @StateObject — для сложных объектов, @Environment — для системных значений из иерархии.

Выбор конкретного Property Wrapper зависит от источника данных и их жизненного цикла. Если данные принадлежат одному view и не нужны дочерним компонентам — используйте @State. Если дочернему view требуется изменять данные родителя — применяйте @Binding. Для объектов, которые используются в нескольких view, подходят @ObservedObject и @StateObject.

@State: локальное состояние представления

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

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

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

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

@Binding: двусторонняя связь между view

@Binding создаёт ссылку на источник данных, принадлежащий другому view. Binding не хранит значение самостоятельно — он читает и записывает данные через @State, @StateObject или другой Binding, переданный из родителя. Это позволяет дочерним компонентам модифицировать состояние предка без прямого владения данными и без коллбэков.

struct ToggleSwitch: View {
    @Binding var isOn: Bool

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

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

@ObservedObject и @StateObject: внешние данные

@ObservedObject — это Property Wrapper для наблюдения за экземпляром ObservableObject, переданным извне. View не владеет этим объектом — он создаётся в родительском компоненте или внедряется через Environment. Когда любое @Published свойство внутри ObservableObject изменяется, SwiftUI перерисовывает все view, подписанные через @ObservedObject.

@StateObject — обёртка для создания и владения ObservableObject непосредственно во view. В отличие от @ObservedObject, @StateObject гарантирует единственный экземпляр объекта на весь жизненный цикл view. Даже если 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("Hello, \(settings.username)")
    }
}

В примере ProfileView создаёт UserSettings через @StateObject, становясь владельцем объекта. ChildProfileView получает тот же экземпляр через @ObservedObject — наблюдает, но не управляет жизненным циклом. При изменении username оба view обновляются. Если бы ChildProfileView использовал @StateObject вместо @ObservedObject, при каждом рендере создавался бы новый экземпляр с начальным значением.

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

Создание собственного 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 использует дженерик T для работы с любым тип данных, поддерживаемым UserDefaults. Геттер читает значение по ключу, сеттер записывает. Применение @UserDefaultsWrapper(key:defaultValue:) к свойству theme автоматически связывает его с хранилищем — вся логика работы с UserDefaults спрятана внутри обёртки. Это типичный пример снижения шаблонного кода с помощью Property Wrappers.

При создании собственных обёрток важно учитывать производительность. Поскольку геттер и сеттер вызываются при каждом доступе к свойству, не следует помещать в wrappedValue тяжёлые I/O-операции. Для асинхронного хранения данных лучше комбинировать Property Wrappers с ObservableObject и @Published.