swiftui-patterns

Padrões SwiftUI

Padrões modernos de SwiftUI para construir interfaces de usuário declarativas e performáticas nas plataformas Apple. Abrange o framework Observation, composição de views, navegação type-safe e otimização de desempenho.

Quando Ativar

• Construindo views SwiftUI e gerenciando estado (@State, @Observable, @Binding)
• Projetando fluxos de navegação com NavigationStack
• Estruturando view models e fluxo de dados
• Otimizando desempenho de renderização para listas e layouts complexos
• Trabalhando com valores de ambiente e injeção de dependência no SwiftUI

Gerenciamento de Estado

Seleção de Property Wrappers

Escolha o wrapper mais simples que se encaixa:

Wrapper	Caso de Uso
@State	Tipos de valor locais da view (toggle, campos de formulário, apresentação de sheet)
@Binding	Referência bidirecional ao @State da view pai
Classe @Observable + @State	Modelo próprio com múltiplas propriedades
Classe @Observable (sem wrapper)	Referência somente leitura passada da view pai
@Bindable	Ligação bidirecional a uma propriedade @Observable
@Environment	Dependências compartilhadas injetadas via .environment()

ViewModel com @Observable

Use @Observable (não ObservableObject) — ele rastreia mudanças no nível da propriedade, de modo que o SwiftUI só re-renderiza views que leem a propriedade alterada:

@Observable
final class ItemListViewModel {
    private(set) var items: [Item] = []
    private(set) var isLoading = false
    var searchText = ""

    private let repository: any ItemRepository

    init(repository: any ItemRepository = DefaultItemRepository()) {
        self.repository = repository
    }

    func load() async {
        isLoading = true
        defer { isLoading = false }
        items = (try? await repository.fetchAll()) ?? []
    }
}

View Consumindo o ViewModel

struct ItemListView: View {
    @State private var viewModel: ItemListViewModel

    init(viewModel: ItemListViewModel = ItemListViewModel()) {
        _viewModel = State(initialValue: viewModel)
    }

    var body: some View {
        List(viewModel.items) { item in
            ItemRow(item: item)
        }
        .searchable(text: $viewModel.searchText)
        .overlay { if viewModel.isLoading { ProgressView() } }
        .task { await viewModel.load() }
    }
}

Injeção de Ambiente

Substitua @EnvironmentObject por @Environment:

// Injetar
ContentView()
    .environment(authManager)

// Consumir
struct ProfileView: View {
    @Environment(AuthManager.self) private var auth

    var body: some View {
        Text(auth.currentUser?.name ?? "Convidado")
    }
}

Composição de Views

Extrair Subviews para Limitar Invalidação

Divida views em structs pequenas e focadas. Quando o estado muda, apenas a subview que lê aquele estado re-renderiza:

struct OrderView: View {
    @State private var viewModel = OrderViewModel()

    var body: some View {
        VStack {
            OrderHeader(title: viewModel.title)
            OrderItemList(items: viewModel.items)
            OrderTotal(total: viewModel.total)
        }
    }
}

ViewModifier para Estilização Reutilizável

struct CardModifier: ViewModifier {
    func body(content: Content) -> some View {
        content
            .padding()
            .background(.regularMaterial)
            .clipShape(RoundedRectangle(cornerRadius: 12))
    }
}

extension View {
    func cardStyle() -> some View {
        modifier(CardModifier())
    }
}

Navegação

NavigationStack Type-Safe

Use NavigationStack com NavigationPath para roteamento programático e type-safe:

@Observable
final class Router {
    var path = NavigationPath()

    func navigate(to destination: Destination) {
        path.append(destination)
    }

    func popToRoot() {
        path = NavigationPath()
    }
}

enum Destination: Hashable {
    case detail(Item.ID)
    case settings
    case profile(User.ID)
}

struct RootView: View {
    @State private var router = Router()

    var body: some View {
        NavigationStack(path: $router.path) {
            HomeView()
                .navigationDestination(for: Destination.self) { dest in
                    switch dest {
                    case .detail(let id): ItemDetailView(itemID: id)
                    case .settings: SettingsView()
                    case .profile(let id): ProfileView(userID: id)
                    }
                }
        }
        .environment(router)
    }
}

Desempenho

Use Contêineres Lazy para Coleções Grandes

LazyVStack e LazyHStack criam views apenas quando visíveis:

ScrollView {
    LazyVStack(spacing: 8) {
        ForEach(items) { item in
            ItemRow(item: item)
        }
    }
}

Identificadores Estáveis

Sempre use IDs estáveis e únicos em ForEach — evite usar índices de array:

// Use conformidade Identifiable ou id explícito
ForEach(items, id: \.stableID) { item in
    ItemRow(item: item)
}

Evite Trabalho Caro em body

• Nunca realize I/O, chamadas de rede ou computação pesada dentro de body
• Use .task {} para trabalho assíncrono — ele cancela automaticamente quando a view desaparece
• Use .sensoryFeedback() e .geometryGroup() com moderação em scroll views
• Minimize .shadow(), .blur(), e .mask() em listas — eles disparam renderização fora da tela

Conformidade Equatable

Para views com bodies caros, conforme a Equatable para pular re-renderizações desnecessárias:

struct ExpensiveChartView: View, Equatable {
    let dataPoints: [DataPoint] // DataPoint deve estar em conformidade com Equatable

    static func == (lhs: Self, rhs: Self) -> Bool {
        lhs.dataPoints == rhs.dataPoints
    }

    var body: some View {
        // Renderização complexa de gráfico
    }
}

Pré-visualizações

Use macro #Preview com dados mock inline para iteração rápida:

#Preview("Estado vazio") {
    ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository()))
}

#Preview("Carregado") {
    ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository()))
}

Antipadrões a Evitar

• Usar ObservableObject / @Published / @StateObject / @EnvironmentObject em código novo — migre para @Observable
• Colocar trabalho assíncrono diretamente em body ou init — use .task {} ou métodos de carregamento explícitos
• Criar view models como @State dentro de views filhas que não possuem os dados — passe da view pai
• Usar type erasure com AnyView — prefira @ViewBuilder ou Group para views condicionais
• Ignorar requisitos Sendable ao passar dados para/de atores

Referências

Consulte o skill: swift-actor-persistence para padrões de persistência baseados em atores. Consulte o skill: swift-protocol-di-testing para DI baseada em protocolos e testes com Swift Testing.