@FocusState — co to jest, zarządzanie fokusem i klawiaturą w SwiftUI

Co to jest @FocusState w SwiftUI

@FocusState — to property wrapper, który łączy stan fokusu z konkretnym polem wprowadzania lub innym focusable-elementem w SwiftUI. W przeciwieństwie do UIKit, gdzie zarządzanie fokusem odbywa się przez metody becomeFirstResponder i resignFirstResponder, SwiftUI używa deklaratywnego podejścia: deklarujesz stan (@FocusState) i łączysz go z elementem za pomocą modyfikatora .focused(). Zmiana stanu automatycznie zmienia fokus.

Przed pojawieniem się @FocusState w iOS 15 programiści musieli tworzyć UIViewRepresentable opakowania wokół UITextField lub używać zewnętrznych bibliotek. @FocusState jest zintegrowany bezpośrednio z SwiftUI i działa z TextField, TextEditor, SecureField i SearchField. To sprawia, że kod jest czystszy, zmniejsza ilość UIKit-mostków i poprawia testowalność.

Według WWDC Session 10136 — What's new in SwiftUI (2024), @FocusState używa systemu preference-kluczy SwiftUI do przesyłania informacji o fokusie między elementami. Gdy pole otrzymuje fokus, SwiftUI automatycznie aktualizuje powiązaną właściwość @FocusState, co pozwala reagować na zmiany fokusu w kodzie.

Zarządzanie fokusem za pomocą Bool

Najprostszy sposób użycia @FocusState — typ Bool. Gdy pole jest w fokusie, właściwość ma wartość true. Gdy fokus odchodzi — false. Możesz wymusić ustawienie fokusu, przypisując true, lub zresetować go, przypisując false.

struct LoginForm: View {
    @State var email = ""
    @FocusState var isEmailFocused: Bool
    
    var body: some View {
        VStack {
            TextField("Email", text: $email)
                .focused($isEmailFocused)
            
            Button("Pokaż klawiaturę") {
                isEmailFocused = true
            }
            Button("Ukryj klawiaturę") {
                isEmailFocused = false
            }
        }
    }
}

W tym przykładzie isEmailFocused automatycznie staje się true, gdy użytkownik dotknie pola tekstowego, i false, gdy klawiatura jest ukrywana. Przyciski umożliwiają programowe zarządzanie fokusem — jest to przydatne dla niestandardowych klawiatur, przycisków „Dalej” i sytuacji, gdy trzeba wymusić ukrycie klawiatury po wysłaniu formularza.

Zarządzanie fokusem za pomocą Enum dla wielu pól

Dla formularzy z wieloma polami @FocusState obsługuje enum zgodny z protokołem FocusStateValue (lub Hashable). Każdy case enum odpowiada konkretnemu polu. Pozwala to przełączać fokus między polami — na przykład przy naciśnięciu „Dalej” na klawiaturze przechodzić do następnego pola.

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

Zwóć uwagę na modyfikator .onSubmit — jest wywoływany, gdy użytkownik naciśnie „Return” na klawiaturze. Wewnątrz .onSubmit przełączamy focusedField na następne pole, co automatycznie przenosi fokus. Ostatnie pole wywołuje submitForm() w celu wysłania formularza.

Ukrywanie i pokazywanie klawiatury

@FocusState zapewnia prosty sposób ukrycia klawiatury — wystarczy ustawić właściwość na nil (dla enum) lub false (dla Bool). Czasami jednak trzeba ukryć klawiaturę bez wiązania z konkretnym polem — na przykład przy dotknięciu pustego miejsca. W tym przypadku jest kilka podejść.

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

Modyfikator .toolbar z placement .keyboard dodaje przycisk nad klawiaturą. Jest to standardowy wzorzec UX w iOS do ukrywania klawiatury. Alternatywne podejście — użycie .onTapGesture na głównym VStack do zresetowania fokusu przy dotknięciu tła.

Fokus i walidacja formularza

@FocusState doskonale łączy się z walidacją formularza. Typowy wzorzec: po naciśnięciu przycisku „Wyślij” sprawdź wszystkie pola i ustaw fokus na pierwszym polu z błędem. Poprawia to doświadczenie użytkownika — użytkownik od razu widzi, które pole wymaga poprawy.

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("Wyślij") { validateAndSubmit() }
        }
    }
    
    func validateAndSubmit() {
        if name.isEmpty {
            focusedField = .name
            return
        }
        if phone.isEmpty {
            focusedField = .phone
            return
        }
        // prześlij formularz
    }
}

W tym przykładzie, gdy pole name jest puste, fokus przenosi się na nie, a użytkownik od razu widzi, gdzie jest błąd. Jeśli name jest wypełnione, sprawdzane jest phone. Jest to naturalne zachowanie dla formularzy — użytkownik wypełnia pola od góry do dołu, a walidacja podąża w tej samej kolejności.

Typowe błędy z @FocusState

Najczęstszy błąd — próba użycia @FocusState z typem niezgodnym z Hashable. @FocusState wymaga, aby typ właściwości był Hashable (Bool i opcjonalne enum już są zgodne). Jeśli próbujesz użyć niestandardowej struktury, upewnij się, że implementuje Hashable.

• Zapomniałeś modyfikatora .focused() — @FocusState sam w sobie nie zarządza fokusem. Trzeba koniecznie połączyć go z polem przez .focused($property) lub .focused($property, equals: .case).
• Wiele @FocusState w jednym View — dla wielu pól użyj jednego @FocusState z enum, a nie wielu właściwości @FocusState. Wiele właściwości Bool nie będzie ze sobą zsynchronizowanych.
• Zmiana @FocusState poza main thread — @FocusState należy zmieniać tylko na głównym wątku, podobnie jak wszystkie właściwości UI w SwiftUI. Operacje asynchroniczne powinny przełączać się na MainActor przed zmianą.
• Resetowanie fokusu przy przebudowie — jeśli View jest przebudowywany, @FocusState może zostać zresetowany. Użyj modyfikatora .id() dla stabilnej identyfikacji View.

// ❌ Błąd: dwa @FocusState Bool zamiast enum
@FocusState var isNameFocused: Bool
@FocusState var isEmailFocused: Bool

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