PreviewProvider — что это, протокол SwiftUI и настройка в Xcode

Что такое PreviewProvider?

PreviewProvider — протокол SwiftUI, определяющий контракт для создания превью-контента в Xcode Canvas. Протокол содержит единственное обязательное свойство: previews типа some View. Любое значение, возвращаемое previews, отображается в Canvas как интерактивная превью. PreviewProvider не требует наследования — достаточно статической реализации в extension.

Архитектурно PreviewProvider не является частью рантайма SwiftUI — это исключительно инструмент разработки. Протокол маркирован атрибутом @available(iOS 13.0, *) и не компилируется в релизную сборку, так как Xcode использует conditional compilation для исключения превью-кода из production. Это значит, что PreviewProvider не влияет на размер бинарника и производительность приложения.

Протокол previews

Свойство previews — единственное требование PreviewProvider. Оно должно возвращать любую View: от простого Text до сложной иерархии с Group и ForEach. Xcode рендерит возвращённую View в Canvas, применяя системные настройки (тему, размер, шрифт).

import SwiftUI

struct GreetingView: View {
    let name: String
    
    var body: some View {
        Text("Hello, \(name)!")
            .padding()
    }
}

// PreviewProvider — static implementation
struct GreetingView_Previews: PreviewProvider {
    static var previews: some View {
        GreetingView(name: "World")
    }
}

Конвенция именования: Apple рекомендует называть структуру превью как {ViewName}_Previews. Это не является обязательным требованием компилятора, но улучшает читаемость и навигацию по проекту. Xcode автоматически подставляет этот шаблон при создании нового SwiftUI файла.

Как работает PreviewProvider: протокол и метод previews

Механизм работы PreviewProvider основан на статической диспетчеризации: Xcode компилирует extension с PreviewProvider только для Debug-конфигурации и вызывает previews в процессе построения Canvas. Каждый раз при изменении кода Xcode перекомпилирует только изменённые PreviewProvider, что обеспечивает near-instant preview обновление.

SwiftUI не гарантирует точное соответствие превью финальному UI на симуляторе или устройстве — Canvas использует упрощённый рендеринг. Анимации с задержками могут отображаться некорректно, а некоторые UIKit-компоненты (MapKit, WebView) не рендерятся в Canvas без дополнительной настройки.

Множественные превью через Group

Group позволяет отобразить несколько состояний одной View одновременно, что ускоряет итерацию при верстке различных конфигураций. Каждое превью внутри Group рендерится независимо.

struct ButtonView_Previews: PreviewProvider {
    static var previews: some View {
        Group {
            ButtonView(title: "Primary", style: .primary)
                .previewDisplayName("Primary")
            
            ButtonView(title: "Disabled", style: .primary)
                .disabled(true)
                .previewDisplayName("Disabled")
            
            ButtonView(title: "Secondary", style: .secondary)
                .previewDisplayName("Secondary")
        }
    }
}

previewDisplayName добавляет подпись к каждому превью в Canvas, что особенно удобно при сравнении нескольких состояний. Максимальное количество превью в Group не ограничено, но более 6–8 замедляют Canvas.

Настройка превью в Xcode

Xcode предоставляет несколько модификаторов для настройки отображения превью. Основные: previewDevice — эмулирует конкретное устройство (iPhone 16 Pro, iPad Air, Apple Watch Ultra), previewLayout — задаёт размер (device, fixed, sizeThatFits). Комбинация этих модификаторов даёт полный контроль над превью-окружением.

previewDevice принимает строку с именем устройства, например "iPhone 16 Pro" или "iPad Pro 13-inch (M4)". Список доступных устройств зависит от установленных симуляторов в Xcode. Если устройство не найдено, Canvas отображает превью на устройстве по умолчанию без ошибки.

Превью для разных устройств

Распространённая практика — показывать одну View на нескольких устройствах одновременно, чтобы проверить адаптивность. Для этого используется ForEach с массивом имён устройств.

struct AdaptiveView_Previews: PreviewProvider {
    static var previews: some View {
        ForEach(["iPhone SE (3rd generation)", "iPhone 16 Pro Max", "iPad Pro 13-inch (M4)"], id: \.self) { device in
            AdaptiveView()
                .previewDevice(.previewDevice(device))
                .previewDisplayName(device)
        }
    }
}

Примеры PreviewProvider

Практические примеры показывают различные сценарии использования PreviewProvider: от простого превью до сложных конфигураций с live-данными и UIKit-совместимостью.

Превью с мок-данными

Мок-данные — стандартный паттерн для превью, когда View принимает модель. Вместо реального API подставляются тестовые данные, что позволяет визуально проверить состояние UI без запуска приложения.

struct UserProfileView: View {
    let user: User
    
    var body: some View {
        VStack {
            AsyncImage(url: user.avatarURL)
                .clipShape(Circle())
            Text(user.name)
                .font(.title)
            Text(user.bio)
                .font(.body)
                .foregroundColor(.secondary)
        }
    }
}

struct UserProfileView_Previews: PreviewProvider {
    static var previews: some View {
        UserProfileView(user: .mock)
            .previewDisplayName("Profile")
        
        UserProfileView(user: .mockLongName)
            .previewDisplayName("Long Name")
    }
}

UIKit-превью через UIViewRepresentable

UIKit-совместимость — PreviewProvider работает и с UIKit-компонентами, обёрнутыми в UIViewRepresentable. Это позволяет превьюрить существующие UIKit-вью в SwiftUI Canvas без миграции всего проекта.

struct MapViewRepresentable: UIViewRepresentable {
    func makeUIView(context: Context) -> MKMapView {
        MKMapView()
    }
    
    func updateUIView(_ uiView: MKMapView, context: Context) {
        // Configure map
    }
}

struct MapView_Previews: PreviewProvider {
    static var previews: some View {
        MapViewRepresentable()
    }
}

PreviewProvider и SwiftUI Canvas

Canvas — это визуальный редактор Xcode, который рендерит результат работы PreviewProvider в реальном времени. Без реализации PreviewProvider Canvas остаётся пустым. Canvas и PreviewProvider работают в паре: PreviewProvider определяет что показывать, Canvas — где и как.

Важно понимать: Canvas — это среда выполнения превью, а не альтернатива PreviewProvider. Даже если разработчик не открывает Canvas, PreviewProvider может использоваться для быстрой проверки кода через всплывающее превью при наведении на иконку Canvas. По данным WWDC 2024, Apple рекомендует писать PreviewProvider для каждой View как стандарт разработки, аналогичный написанию unit-тестов.

Рекомендация: пишите PreviewProvider для каждой публичной View в проекте. Это ускоряет онбординг новых разработчиков, упрощает code review и позволяет быстро проверять визуальные изменения без сборки всего проекта.

Типичные проблемы с PreviewProvider

Проблема 1: Preview не обновляется. Если Canvas не отражает изменения кода, причина чаще всего в кэше DerivedData. Очистите DerivedData через Product → Clean Build Folder (⇧⌘K) или вручную удалив папку ~/Library/Developer/Xcode/DerivedData. После очистки Canvas перестраивает превью заново.

Проблема 2: PreviewProvider не видит @StateObject. PreviewProvider создаёт статический экземпляр View, поэтому зависимости, требующие инъекции (ViewModels, сервисы), должны передаваться через инициализатор или @StateObject с дефолтным значением. Используйте мок-объекты вместо реальных сервисов в превью.

Проблема 3: Анимации не работают в Canvas. Canvas не поддерживает все анимации SwiftUI — особенно те, что зависят от времени (withAnimation с задержкой, .spring). Для проверки анимаций запускайте приложение на симуляторе. Canvas подходит для статической проверки layout.

Исправление PreviewProvider с зависимостями

Инъекция зависимостей — лучший способ сделать PreviewProvider рабочим со сложными ViewModel. Создайте отдельный экземпляр ViewModel с тестовыми данными и передайте его в инициализатор View.

struct DashboardView: View {
    @StateObject var viewModel: DashboardViewModel
    
    var body: some View {
        List(viewModel.items) { item in
            Text(item.title)
        }
    }
}

struct DashboardView_Previews: PreviewProvider {
    static var previews: some View {
        DashboardView(viewModel: DashboardViewModel.mock)
    }
}

Mock-расширения: создайте extension для ViewModel, который предоставляет статические .mock экземпляры. Это держит тестовые данные рядом с ViewModel и делает PreviewProvider читаемым.