Structure

FocusState

A property wrapper type that can read and write a value that SwiftUI updates as the placement of focus within the scene changes.

Declaration 宣言

@frozen @propertyWrapper struct FocusState<Value> where Value : Hashable

Overview 概要

Use this property wrapper in conjunction with focused(_:equals:) and focused(_:) to describe views whose appearance and contents relate to the location of focus in the scene. When focus enters the modified view, the wrapped value of this property updates to match a given prototype value. Similarly, when focus leaves, the wrapped value of this property resets to nil or false. Setting the property’s value programmatically has the reverse effect, causing focus to move to the view associated with the updated value.

In the following example of a simple login screen, when the user presses the Sign In button and one of the fields is still empty, focus moves to that field. Otherwise, the sign-in process proceeds.


struct LoginForm {
    enum Field: Hashable {
        case username
        case password
    }


    @State private var username = ""
    @State private var password = ""
    @FocusState private var focusedField: Field?


    var body: some View {
        Form {
            TextField("Username", text: $username)
                .focused($focusedField, equals: .username)


            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)


            Button("Sign In") {
                if username.isEmpty {
                    focusedField = .username
                } else if password.isEmpty {
                    focusedField = .password
                } else {
                    handleLogin(username, password)
                }
            }
        }
    }
}

To allow for cases where focus is completely absent from a view tree, the wrapped value must be either an optional or a Boolean. Set the focus binding to false or nil as appropriate to remove focus from all bound fields. You can also use this to remove focus from a TextField and thereby dismiss the keyboard.

Avoid Ambiguous Focus Bindings

The same view can have multiple focus bindings. In the following example, setting focusedField to either name or fullName causes the field to receive focus:


struct ContentView: View {
    enum Field: Hashable {
        case name
        case fullName
    }
    @FocusState private var focusedField: Field?


    var body: some View {
        TextField("Full Name", ...)
            .focused($focusedField, equals: .name)
            .focused($focusedField, equals: .fullName)
    }
}

On the other hand, binding the same value to two views is ambiguous. In the following example, two separate fields bind focus to the name value:


struct ContentView: View {
    enum Field: Hashable {
        case name
        case fullName
    }
    @FocusState private var focusedField: Field?


    var body: some View {
        TextField("Name", ...)
            .focused($focusedField, equals: .name)
        TextField("Full Name", ...)
            .focused($focusedField, equals: .name) // incorrect re-use of .name
    }
}

If the user moves focus to either field, the focusedField binding updates to name. However, if the app programmatically sets the value to name, SwiftUI chooses the first candidate, which in this case is the “Name” field. SwiftUI also emits a runtime warning in this case, since the repeated binding is likely a programmer error.

Topics 話題

Creating a Focus State

Inspecting the Focus State

Default Implementations 省略時実装

Relationships 関係

Conforms To 次に準拠

See Also 参照

Focus