@FocusState — che cos'è, gestione del focus e della tastiera in SwiftUI

Cos'è @FocusState in SwiftUI

@FocusState è un property wrapper che lega lo stato del focus a un campo di input specifico o a un altro elemento focusabile in SwiftUI. A differenza di UIKit, dove la gestione del focus avviene tramite i metodi becomeFirstResponder e resignFirstResponder, SwiftUI utilizza un approccio dichiarativo: si dichiara uno stato (@FocusState) e lo si lega a un elemento tramite il modificatore .focused(). Modificare lo stato cambia automaticamente il focus.

Prima dell'introduzione di @FocusState in iOS 15, gli sviluppatori dovevano creare wrapper UIViewRepresentable attorno a UITextField o usare librerie di terze parti. @FocusState è integrato direttamente in SwiftUI e funziona con TextField, TextEditor, SecureField e SearchField. Questo rende il codice più pulito, riduce il numero di ponti UIKit e migliora la testabilità.

Secondo WWDC Session 10136 — What's new in SwiftUI (2024), @FocusState utilizza il sistema di preference keys di SwiftUI per passare le informazioni di focus tra gli elementi. Quando un campo riceve il focus, SwiftUI aggiorna automaticamente la proprietà @FocusState associata, consentendo di reagire alle modifiche del focus nel codice.

Gestione del focus con Bool

Il modo più semplice per usare @FocusState è con il tipo Bool. Quando un campo è focalizzato, la proprietà è true. Quando il focus viene perso — false. È possibile forzare il focus impostandolo a true o rimuoverlo impostandolo a false.

struct LoginForm: View {
    @State var email = ""
    @FocusState var isEmailFocused: Bool
    
    var body: some View {
        VStack {
            TextField("Email", text: $email)
                .focused($isEmailFocused)
            
            Button("Mostra tastiera") {
                isEmailFocused = true
            }
            Button("Nascondi tastiera") {
                isEmailFocused = false
            }
        }
    }
}

In questo esempio, isEmailFocused diventa automaticamente true quando l'utente tocca il campo di testo e false quando la tastiera viene nascosta. I pulsanti consentono di gestire il focus in modo programmatico — utile per tastiere personalizzate, pulsanti "Avanti" e situazioni in cui è necessario nascondere forzatamente la tastiera dopo l'invio del modulo.

Gestione del focus con Enum per più campi

Per moduli con più campi, @FocusState supporta un enum conforme al protocollo FocusStateValue (o Hashable). Ogni case dell'enum corrisponde a un campo specifico. Ciò consente di spostare il focus tra i campi — ad esempio, quando l'utente preme "Avanti" sulla tastiera per passare al campo successivo.

struct RegistrationForm: View {
    enum Field: Hashable {
        case email
        case password
        case confirmPassword
    }
    
    @State var email = ""
    @State var password = ""
    @State var confirmPassword = ""
    @FocusState var focusedField: Field?
    
    var body: some View {
        Form {
            TextField("Email", text: $email)
                .focused($focusedField, equals: .email)
                .onSubmit { focusedField = .password }
            
            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)
                .onSubmit { focusedField = .confirmPassword }
            
            SecureField("Confirm", text: $confirmPassword)
                .focused($focusedField, equals: .confirmPassword)
                .onSubmit { submitForm() }
        }
    }
}

Nota il modificatore .onSubmit — viene chiamato quando l'utente preme "Return" sulla tastiera. All'interno di .onSubmit spostiamo focusedField al campo successivo, che sposta automaticamente il focus. L'ultimo campo chiama submitForm() per inviare il modulo.

Mostrare e nascondere la tastiera

@FocusState fornisce un modo semplice per nascondere la tastiera — basta impostare la proprietà su nil (per enum) o false (per Bool). Tuttavia, a volte è necessario nascondere la tastiera senza legarla a un campo specifico — ad esempio, toccando uno spazio vuoto. In questo caso, esistono diversi approcci.

struct DismissKeyboardView: View {
    @State var text = ""
    @FocusState var isFocused: Bool
    
    var body: some View {
        TextField("Enter text", text: $text)
            .focused($isFocused)
            .toolbar {
                ToolbarItemGroup(placement: .keyboard) {
                    Spacer()
                    Button("Fatto") {
                        isFocused = false
                    }
                }
            }
    }
}

Il modificatore .toolbar con placement .keyboard aggiunge un pulsante sopra la tastiera. Questo è un pattern UX standard in iOS per nascondere la tastiera. Un approccio alternativo è usare .onTapGesture sul VStack radice per reimpostare il focus toccando lo sfondo.

Focus e validazione dei moduli

@FocusState si combina perfettamente con la validazione dei moduli. Un pattern tipico: dopo aver premuto il pulsante "Invia", validare tutti i campi e impostare il focus sul primo campo con errore. Questo migliora l'esperienza utente — l'utente vede immediatamente quale campo deve essere corretto.

struct ValidatedForm: View {
    enum Field: Hashable { case name; case phone }
    
    @State var name = ""
    @State var phone = ""
    @FocusState var focusedField: Field?
    @State var errors: [String] = []
    
    var body: some View {
        Form {
            TextField("Name", text: $name)
                .focused($focusedField, equals: .name)
            TextField("Phone", text: $phone)
                .focused($focusedField, equals: .phone)
            
            Button("Invia") { validateAndSubmit() }
        }
    }
    
    func validateAndSubmit() {
        if name.isEmpty {
            focusedField = .name
            return
        }
        if phone.isEmpty {
            focusedField = .phone
            return
        }
        // invia modulo
    }
}

In questo esempio, se il campo name è vuoto, il focus si sposta su di esso e l'utente vede immediatamente dov'è l'errore. Se name è compilato, viene controllato phone. Questo è un comportamento naturale per i moduli — l'utente compila i campi dall'alto verso il basso e la validazione segue lo stesso ordine.

Errori comuni con @FocusState

L'errore più comune è cercare di usare @FocusState con un tipo che non è conforme a Hashable. @FocusState richiede che il tipo della proprietà sia Hashable (Bool ed enum opzionali sono già conformi). Se si sta cercando di usare una struttura personalizzata, assicurarsi che implementi Hashable.

• Modificatore .focused() dimenticato — @FocusState da solo non gestisce il focus. È necessario legarlo a un campo tramite .focused($property) o .focused($property, equals: .case).
• Più @FocusState in una sola View — per più campi, usa un singolo @FocusState con un enum, non più proprietà @FocusState. Più proprietà Bool non saranno sincronizzate tra loro.
• Modificare @FocusState al di fuori del thread principale — @FocusState dovrebbe essere modificato solo sul thread principale, come tutte le proprietà UI in SwiftUI. Le operazioni asincrone devono passare a MainActor prima di modificarlo.
• Reimpostazione del focus durante la ricostruzione della View — se la View viene ricostruita, @FocusState potrebbe reimpostarsi. Usa il modificatore .id() per un'identificazione stabile della View.

// ❌ Errore: due @FocusState Bool invece di enum
@FocusState var isNameFocused: Bool
@FocusState var isEmailFocused: Bool

// ✅ Corretto: singolo enum @FocusState
enum Field: Hashable { case name; case email }
@FocusState var focusedField: Field?