@FocusState — qu'est-ce que c'est, gestion du focus et du clavier dans SwiftUI

Qu'est-ce que @FocusState dans SwiftUI

@FocusState est un property wrapper qui lie l'état du focus à un champ de saisie spécifique ou à un autre élément focusable dans SwiftUI. Contrairement à UIKit, où la gestion du focus se fait via les méthodes becomeFirstResponder et resignFirstResponder, SwiftUI utilise une approche déclarative : vous déclarez un état (@FocusState) et le liez à un élément via le modificateur .focused(). Changer l'état change automatiquement le focus.

Avant l'introduction de @FocusState dans iOS 15, les développeurs devaient créer des wrappers UIViewRepresentable autour de UITextField ou utiliser des bibliothèques tierces. @FocusState est intégré directement dans SwiftUI et fonctionne avec TextField, TextEditor, SecureField et SearchField. Cela rend le code plus propre, réduit le nombre de ponts UIKit et améliore la testabilité.

Selon WWDC Session 10136 — What's new in SwiftUI (2024), @FocusState utilise le système de preference keys de SwiftUI pour transmettre les informations de focus entre les éléments. Lorsqu'un champ reçoit le focus, SwiftUI met automatiquement à jour la propriété @FocusState associée, ce qui permet de réagir aux changements de focus dans le code.

Gestion du focus avec Bool

La façon la plus simple d'utiliser @FocusState est avec le type Bool. Lorsqu'un champ est focus, la propriété est true. Lorsque le focus est perdu — false. Vous pouvez forcer le focus en le définissant sur true, ou le supprimer en le définissant sur false.

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

Dans cet exemple, isEmailFocused devient automatiquement true lorsque l'utilisateur tape sur le champ de texte, et false lorsque le clavier est masqué. Les boutons permettent de gérer le focus programmatiquement — utile pour les claviers personnalisés, les boutons "Suivant" et les situations où vous devez masquer de force le clavier après la soumission du formulaire.

Gestion du focus avec Enum pour plusieurs champs

Pour les formulaires avec plusieurs champs, @FocusState prend en charge un enum conforme au protocole FocusStateValue (ou Hashable). Chaque cas de l'enum correspond à un champ spécifique. Cela permet de basculer le focus entre les champs — par exemple, lorsque l'utilisateur appuie sur "Suivant" au clavier pour passer au champ suivant.

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

Notez le modificateur .onSubmit — il est appelé lorsque l'utilisateur appuie sur "Return" au clavier. Dans .onSubmit, nous basculons focusedField vers le champ suivant, ce qui déplace automatiquement le focus. Le dernier champ appelle submitForm() pour soumettre le formulaire.

Masquer et afficher le clavier

@FocusState fournit un moyen simple de masquer le clavier — il suffit de définir la propriété sur nil (pour enum) ou false (pour Bool). Cependant, vous avez parfois besoin de masquer le clavier sans le lier à un champ spécifique — par exemple, en tapant sur un espace vide. Dans ce cas, il existe plusieurs approches.

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("Terminé") {
                        isFocused = false
                    }
                }
            }
    }
}

Le modificateur .toolbar avec placement .keyboard ajoute un bouton au-dessus du clavier. C'est un modèle UX standard dans iOS pour masquer le clavier. Une approche alternative consiste à utiliser .onTapGesture sur le VStack racine pour réinitialiser le focus lors d'un tap sur le fond.

Focus et validation de formulaire

@FocusState se combine parfaitement avec la validation de formulaire. Un modèle typique : après avoir appuyé sur le bouton "Envoyer", validez tous les champs et définissez le focus sur le premier champ avec une erreur. Cela améliore l'expérience utilisateur — l'utilisateur voit immédiatement quel champ doit être corrigé.

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("Soumettre") { validateAndSubmit() }
        }
    }
    
    func validateAndSubmit() {
        if name.isEmpty {
            focusedField = .name
            return
        }
        if phone.isEmpty {
            focusedField = .phone
            return
        }
        // soumettre le formulaire
    }
}

Dans cet exemple, si le champ name est vide, le focus se déplace vers lui, et l'utilisateur voit immédiatement où se trouve l'erreur. Si name est rempli, phone est vérifié. C'est un comportement naturel pour les formulaires — l'utilisateur remplit les champs de haut en bas, et la validation suit le même ordre.

Erreurs courantes avec @FocusState

L'erreur la plus courante est d'essayer d'utiliser @FocusState avec un type qui n'est pas conforme à Hashable. @FocusState exige que le type de la propriété soit Hashable (Bool et les enums optionnels sont déjà conformes). Si vous essayez d'utiliser une structure personnalisée, assurez-vous qu'elle implémente Hashable.

• Modificateur .focused() oublié — @FocusState seul ne gère pas le focus. Vous devez le lier à un champ via .focused($property) ou .focused($property, equals: .case).
• Plusieurs @FocusState dans une même View — pour plusieurs champs, utilisez un seul @FocusState avec un enum, pas plusieurs propriétés @FocusState. Plusieurs propriétés Bool ne seront pas synchronisées entre elles.
• Modification de @FocusState en dehors du thread principal — @FocusState ne doit être modifié que sur le thread principal, comme toutes les propriétés UI dans SwiftUI. Les opérations asynchrones doivent basculer sur MainActor avant de le modifier.
• Réinitialisation du focus lors de la reconstruction de la View — si la View est reconstruite, @FocusState peut se réinitialiser. Utilisez le modificateur .id() pour une identification stable de la View.

// ❌ Erreur : deux @FocusState Bool au lieu d'enum
@FocusState var isNameFocused: Bool
@FocusState var isEmailFocused: Bool

// ✅ Correct : un seul enum @FocusState
enum Field: Hashable { case name; case email }
@FocusState var focusedField: Field?