@FocusState — какво е това, управление на фокуса и клавиатурата в SwiftUI

Какво е @FocusState в SwiftUI

@FocusState — е property wrapper, който свързва състоянието на фокуса с конкретно поле за въвеждане или друг focusable елемент в SwiftUI. За разлика от UIKit, където управлението на фокуса става чрез методите becomeFirstResponder и resignFirstResponder, SwiftUI използва декларативен подход: декларирате състояние (@FocusState) и го свързвате с елемента чрез модификатора .focused(). Промяната на състоянието автоматично променя фокуса.

Преди появата на @FocusState в iOS 15, разработчиците трябваше да създават UIViewRepresentable обвивки около UITextField или да използват библиотеки на трети страни. @FocusState е интегриран директно в SwiftUI и работи с TextField, TextEditor, SecureField и SearchField. Това прави кода по-чист, намалява броя на UIKit мостовете и подобрява тестируемостта.

Според WWDC Session 10136 — What's new in SwiftUI (2024), @FocusState използва системата на preference ключове на SwiftUI за предаване на информация за фокуса между елементите. Когато полето получи фокус, SwiftUI автоматично актуализира свързаното @FocusState свойство, което позволява да реагирате на промените на фокуса в кода.

Управление на фокуса с Bool

Най-простият начин за използване на @FocusState — тип Bool. Когато полето е на фокус, свойството е true. Когато фокусът изчезне — false. Можете принудително да зададете фокуса чрез присвояване на true или да го нулирате чрез присвояване на false.

struct LoginForm: View {
    @State var email = ""
    @FocusState var isEmailFocused: Bool
    
    var body: some View {
        VStack {
            TextField("Email", text: $email)
                .focused($isEmailFocused)
            
            Button("Покажи клавиатурата") {
                isEmailFocused = true
            }
            Button("Скрий клавиатурата") {
                isEmailFocused = false
            }
        }
    }
}

В този пример isEmailFocused автоматично става true, когато потребителят докосне до текстовото поле, и false, когато клавиатурата е скрита. Бутоните позволяват програмно управление на фокуса — полезно за персонализирани клавиатури, бутони „Напред” и ситуации, когато трябва да принудително скриете клавиатурата след изпращане на формуляра.

Управление на фокуса с Enum за много полета

За формуляри с много полета @FocusState поддържа enum, съответстващ на протокол FocusStateValue (или Hashable). Всеки case на enum-а съответства на конкретно поле. Това позволява да превключвате фокуса между полета — например, при натискане на „Напред” на клавиатурата да преминете към следващото поле.

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

Обрнете внимание на модификатора .onSubmit — той се извиква, когато потребителят натисне „Return” на клавиатурата. В тялото на .onSubmit превключваме focusedField към следващото поле, което автоматично премества фокуса. Последното поле извиква submitForm() за изпращане на формуляра.

Скриване и показване на клавиатурата

@FocusState предоставя прост начин за скриване на клавиатурата — достатъчно е да настроите свойството на nil (за enum) или false (за Bool). Понякога обаче трябва да скриете клавиатурата без връзка с конкретно поле — например, при докосване на празно място. В този случай има няколко подхода.

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("Готово") {
                        isFocused = false
                    }
                }
            }
    }
}

Модификаторът .toolbar с placement .keyboard добавя бутон над клавиатурата. Това е стандартен UX модел в iOS за скриване на клавиатурата. Алтернативен подход — използване на .onTapGesture върху основния VStack за нулиране на фокуса при докосване на фона.

Фокус и валидация на формуляр

@FocusState се съчетава отлично с валидацията на формуляра. Типичен модел: след натискане на бутона „Изпрати” проверете всички полета и настройте фокуса на първото поле с грешка. Това подобрява потребителското изживяване — потребителят веднага вижда кое поле трябва да поправи.

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("Изпрати") { validateAndSubmit() }
        }
    }
    
    func validateAndSubmit() {
        if name.isEmpty {
            focusedField = .name
            return
        }
        if phone.isEmpty {
            focusedField = .phone
            return
        }
        // изпрати формуляра
    }
}

В този пример, когато полето name е празно, фокусът се премества върху него и потребителят веднага вижда къде е грешката. Ако name е попълнено, се проверява phone. Това е естествено поведение за формуляри — потребителят попълва полетата отгоре надолу и валидацията следва същия ред.

Типични грешки с @FocusState

Най-често срещаната грешка — опит за използване на @FocusState с тип, който не е Hashable. @FocusState изисква типът на свойството да бъде Hashable (Bool и опционалните enum вече отговарят). Ако опитате да използвате персонализирана структура, убедете се, че тя имплементира Hashable.

• Забравихте модификатора .focused() — @FocusState сам по себе си не управлява фокуса. Трябва задължително да го свържете с полето чрез .focused($property) или .focused($property, equals: .case).
• Няколко @FocusState в едно View — за много полета използвайте един @FocusState с enum, а не няколко @FocusState свойства. Няколко Bool свойства няма да са синхронизирани помежду си.
• Промяна на @FocusState извън на main thread — @FocusState трябва да се променя само в основната нишка, като всички UI свойства в SwiftUI. Асинхронните операции трябва да превключат към MainActor преди промяна.
• Нулиране на фокуса при преизграждане — ако View се преизгражда, @FocusState може да се нулира. Използвайте модификатора .id() за стабилна идентификация на View-то.

// ❌ Грешка: два @FocusState Bool вместо enum
@FocusState var isNameFocused: Bool
@FocusState var isEmailFocused: Bool

// ✅ Правилно: един enum @FocusState
enum Field: Hashable { case name; case email }
@FocusState var focusedField: Field?