SwiftUI 中的 @ViewBuilder 全面解析

SwiftUI 中的 `@ViewBuilder` 全面解析

在 SwiftUI 的世界里，@ViewBuilder 是一个你每天都在用，却可能从未认真了解过的核心机制。

很多 SwiftUI 看起来"像写 DSL 一样优雅"的代码，其实都离不开它。

本文将从为什么需要它、它解决了什么问题、如何使用、常见坑点 几个维度，系统性地介绍 @ViewBuilder，适合 SwiftUI 初学者到中级开发者 阅读。

一、问题的起点：Swift 只能返回一个值

在 Swift 中，函数或计算属性只能返回一个值。

但在 SwiftUI 中，我们却经常写出这样的代码：

swift 复制代码

var body: some View {
    Text("Hello")
    Image(systemName: "star")
    Button("Tap") { }
}

表面看起来像是"返回了多个 View"，这在普通 Swift 函数里是不可能的。

那 SwiftUI 是怎么做到的？

答案就是： @ViewBuilder。

二、`@ViewBuilder` 是什么

@ViewBuilder 是 Swift 的一种 Result Builder（结果构建器） 。

它的核心职责只有一个：

把多行 View 表达式，组合成一个 View 返回。

你写的代码是这样：

swift 复制代码

Text("A")
Text("B")
Text("C")

编译器在背后会帮你组合成类似：

swift 复制代码

TupleView<(Text, Text, Text)>

但这些具体类型对开发者是隐藏的，你只需要关心：

可以像写布局一样写 View，而不是手动拼装结构。

三、为什么你很少看到 `@ViewBuilder`

因为 SwiftUI 已经帮你加好了。

例如：

swift 复制代码

struct ContentView: View {
    var body: some View {
        Text("Hello")
        Text("World")
    }
}

实际上等价于：

swift 复制代码

struct ContentView: View {
    @ViewBuilder
    var body: some View {
        Text("Hello")
        Text("World")
    }
}

👉 body 天生就支持多 View 与条件语法。

四、`@ViewBuilder` 支持哪些能力

1️⃣ 多个 View

swift 复制代码

@ViewBuilder
var content: some View {
    Text("Title")
    Text("Subtitle")
}

2️⃣ `if / else` 条件渲染（非常重要）

没有 @ViewBuilder，下面代码是非法的：

swift 复制代码

func makeView(flag: Bool) -> some View {
    if flag {
        Text("Yes")
    } else {
        Text("No")
    }
}

使用 @ViewBuilder 后：

swift 复制代码

@ViewBuilder
func makeView(flag: Bool) -> some View {
    if flag {
        Text("Yes")
    } else {
        Text("No")
    }
}

👉 这正是 SwiftUI 条件 UI 渲染的基础能力。

3️⃣ 只有 `if`（没有 `else`）

swift 复制代码

@ViewBuilder
var body: some View {
    Text("Always Visible")

    if isLogin {
        Text("Welcome")
    }
}

当条件不成立时，SwiftUI 会自动插入一个 EmptyView。

4️⃣ `switch`

swift 复制代码

@ViewBuilder
func stateView(_ state: LoadState) -> some View {
    switch state {
    case .loading:
        ProgressView()
    case .success:
        Text("Success")
    case .error:
        Text("Error")
    }
}

五、最常见的使用场景

1️⃣ 自定义组件的内容闭包

swift 复制代码

struct Card<Content: View>: View {
    let content: Content

    init(@ViewBuilder content: () -> Content) {
        self.content = content()
    }

    var body: some View {
        VStack(spacing: 8) {
            content
        }
        .padding()
        .background(.gray.opacity(0.2))
        .cornerRadius(12)
    }
}

使用时：

swift 复制代码

Card {
    Text("Title")
    Text("Subtitle")
}

👉 这正是 SwiftUI 组件化体验优秀的原因之一。

2️⃣ 模仿系统 API（如 `.sheet` / `.toolbar`）

swift 复制代码

func customOverlay<Content: View>(
    @ViewBuilder content: () -> Content
) -> some View {
    overlay {
        content()
    }
}

六、常见坑点（非常容易踩）

❌ 1. 不能写普通逻辑代码

swift 复制代码

@ViewBuilder
var body: some View {
    let count = 10 // ❌ 编译错误
    Text("(count)")
}

原因是：

@ViewBuilder 只接受 生成 View 的表达式。

✅ 正确方式：

swift 复制代码

var count: Int { 10 }

@ViewBuilder
var body: some View {
    Text("(count)")
}

❌ 2. 不能直接使用 `for` 循环

swift 复制代码

@ViewBuilder
var body: some View {
    for i in 0..<3 { // ❌
        Text("(i)")
    }
}

✅ 正确方式：

swift 复制代码

ForEach(0..<3, id: .self) { i in
    Text("(i)")
}

七、什么时候需要主动使用 `@ViewBuilder`

当你遇到以下情况时，就该考虑它：

希望一个函数 / 闭包返回 多个 View
需要在返回 View 时使用 if / else / switch
编写 可组合的自定义组件

简单判断法则：

"这个 API 是否应该像 SwiftUI 一样写 UI？"

如果答案是「是」，那基本就需要 @ViewBuilder。

八、总结

@ViewBuilder 是 SwiftUI 的核心基础设施
它让 Swift 支持 声明式 UI 语法
条件渲染、多 View 组合、本质都依赖它
写组件时，合理使用 @ViewBuilder 能极大提升 API 体验

一句话总结：

没有 @ViewBuilder，就没有今天的 SwiftUI。

如果你觉得这篇文章有帮助，欢迎点赞 / 收藏 / 交流 🙌

后续也可以深入聊：

ViewBuilder 源码实现
@ViewBuilder 与 @ToolbarContentBuilder 的区别
SwiftUI 新数据流（@Observable / @Bindable）下的最佳实践

SwiftUI 中的 @ViewBuilder 全面解析