swiftui-patterns

SwiftUI 模式

现代 SwiftUI 模式，用于在苹果平台上构建声明式、高性能的用户界面。涵盖 Observation 框架、视图组合、类型安全导航和性能优化。

何时激活

• 构建 SwiftUI 视图并管理状态（@State、@Observable、@Binding）
• 使用 NavigationStack 设计导航流程
• 组织视图模型和数据流
• 优化列表和复杂布局的渲染性能
• 在 SwiftUI 中处理环境值和依赖注入

状态管理

属性包装器选择

选择最合适的包装器：

包装器	使用场景
@State	视图本地的值类型（开关、表单字段、表单呈现）
@Binding	对父级 @State 的双向引用
@Observable 类 + @State	拥有多个属性的模型
@Observable 类（无包装器）	从父级传递的只读引用
@Bindable	对 @Observable 属性的双向绑定
@Environment	通过 .environment() 注入的共享依赖

@Observable 视图模型

使用 @Observable（而非 ObservableObject）——它追踪属性级变化，使得 SwiftUI 仅更新读取了变化属性的视图：

@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()) ?? []
    }
}

消费视图模型的视图

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() }
    }
}

环境注入

使用 @Environment 替代 @EnvironmentObject：

// 注入
ContentView()
    .environment(authManager)

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

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

视图组合

提取子视图以限制失效范围

将视图分解为小型、专注的结构体。当状态变化时，只有读取该状态的子视图会重新渲染：

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

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())
    }
}

导航

类型安全的 NavigationStack

使用 NavigationStack 配合 NavigationPath 实现程序化、类型安全的路由：

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

性能

对大型集合使用惰性容器

LazyVStack 和 LazyHStack 仅在视图可见时才创建它们：

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

稳定的标识符

始终在 ForEach 中使用稳定、唯一的 ID——避免使用数组索引：

// 使用 Identifiable 一致性或显式 id
ForEach(items, id: \.stableID) { item in
    ItemRow(item: item)
}

避免在 body 中进行耗时操作

• 绝不在 body 内执行 I/O、网络调用或繁重计算
• 使用 .task {} 进行异步工作——当视图消失时会自动取消
• 在滚动视图中谨慎使用 .sensoryFeedback() 和 .geometryGroup()
• 尽量减少列表中的 .shadow()、.blur() 和 .mask()——它们会触发离屏渲染

Equatable 一致性

对于具有昂贵 body 的视图，遵循 Equatable 以跳过不必要的重渲染：

struct ExpensiveChartView: View, Equatable {
    let dataPoints: [DataPoint] // DataPoint 必须遵循 Equatable

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

    var body: some View {
        // 复杂的图表渲染
    }
}

预览

使用 #Preview 宏配合内联模拟数据实现快速迭代：

#Preview("空状态") {
    ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository()))
}

#Preview("已加载") {
    ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository()))
}

应避免的反模式

• 在新代码中使用 ObservableObject / @Published / @StateObject / @EnvironmentObject——请迁移至 @Observable
• 将异步工作直接放在 body 或 init 中——使用 .task {} 或显式的加载方法
• 在并不拥有数据的子视图中将视图模型创建为 @State——应从父视图传递
• 使用 AnyView 类型擦除——对于条件视图，优先使用 @ViewBuilder 或 Group
• 在向 actors 传递数据时忽略 Sendable 要求

参考

参见技能：swift-actor-persistence 以获取基于 actor 的持久化模式。 参见技能：swift-protocol-di-testing 以获取基于协议的依赖注入和使用 Swift Testing 的测试。