跳转至
Structure

ViewBuilder

A property wrapper that lets you build views declaratively.

Declaration

@\_functionBuilder struct ViewBuilder

Overview

ViewBuilder is used extensively in SwiftUI to let you create new on-screen views by just listing them out in a trailing closure. It's a property wrapper applied to function parameter. Usually, it's just working behind the scenes, so you don't have to worry about it. But, you can also define your own functions that are view builders, and also include them in your own custom views.

(A view builder is just specific type of result builder that you can use with Views. Check out that link to learn more about using these to write clean code.)

Using a ViewBuilder as a trailing closure

ViewBuilder works behind the scenes of many common SwiftUI views - like VStack and HStack. For example, here is the declaration of Group's initializer:

public init(@ViewBuilder content: () -> Content) {
    // Implementation here
}
Since that last parameter is a ViewBuilders, you can easily create a Group by passing it a trailing closure stacking views:

struct ContentView: View {
    var body: some View {
        Group {
            Text("I'm in the group 😁")
            Text("Me too 🥂")
        }
    }
}
1F38B3B4-1BCC-426D-BEB1-D365A09E5C30

Using a ViewBuilder as a function

You can also use ViewBuilder as a function. Just tag your function with @ViewBuilder, and use it just like you would with a trailing closure:

struct ContentView: View {
    var body: some View {
        Group(content: contentBuilder)
    }

    @ViewBuilder
    func contentBuilder() -> some View {
        Text("This is another way to create a Group 👥")
        Text("Just stack the views 🥞")
    }
}
5464434F-469F-4385-BFBE-C9B38C911F56

Using a ViewBuilder in your own Views

Exactly like Group, you can also use ViewBuilders in your own custom views. Just tag the parameter of your View's initializer with @ViewBuilder, and anyone using your view will be able to easily pass you views just by listing them.

In the example below, we use this technique to create a special type of Group that makes everything green. Note that ViewBuilders are actually functions, so in order to get the content they contain, you have to call the function. Below, this is done with content().

struct ContentView: View {
    var body: some View {
        GreenGroup {
            Text("I am green 🤑")
            Text("Hey same 🐲")
        }
    }
}


struct GreenGroup<Content>: View where Content: View {
    var views: Content

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

    var body: some View {
        Group {
            views.foregroundColor(.green)
        }
    }
}
79B81C88-83A4-47C2-B3E7-68BAFFB230E4

Availability

iOS 13.0+

macOS 10.15+

tvOS 13.0+

watchOS 6.0+

Topics


Type Method

buildBlock() Builds an empty view from a block containing no statements.

buildBlock(_:) Passes a single view written as a child view through unmodified.

buildBlock(_:_:) Builds a tuple view for display from 2 views in a view builder.

buildBlock(_:_:_:) Builds a tuple view for display from 3 views in a view builder.

buildBlock(_:_:_:_:) Builds a tuple view for display from 4 views in a view builder.

buildBlock(_:_:_:_:_:) Builds a tuple view for display from 5 views in a view builder.

buildBlock(_:_:_:_:_:_:) Builds a tuple view for display from 6 views in a view builder.

buildBlock(_:_:_:_:_:_:_:) Builds a tuple view for display from 7 views in a view builder.

buildBlock(_:_:_:_:_:_:_:_:) Builds a tuple view for display from 8 views in a view builder.

buildBlock(_:_:_:_:_:_:_:_:_:) Builds a tuple view for display from 9 views in a view builder.

buildBlock(_:_:_:_:_:_:_:_:_:_:) Builds a tuple view for display from 10 views in a view builder.

buildEither(first:) Provides support for "if" statements in multi-statement closures, producing conditional content for the "then" branch.

buildEither(second:) Provides support for "if-else" statements in multi-statement closures, producing conditional content for the "else" branch.

buildIf(_:) Provides support for “if” statements in multi-statement closures, producing an optional view that is visible only when the condition evaluates to true.

buildLimitedAvailability(_:) Provides support for "if" statements with #available() clauses in multi-statement closures, producing conditional content for the "then" branch, i.e. the conditionally-available branch.