@FocusState — ما هو، إدارة التركيز ولوحة المفاتيح في SwiftUI

ما هو @FocusState في SwiftUI

@FocusState هو property wrapper يربط حالة التركيز بحقل إدخال محدد أو عنصر آخر قابل للتركيز في 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 keys في 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). كل حالة من 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 و enums الاختيارية متوافقة بالفعل). إذا كنت تحاول استخدام بنية مخصصة، تأكد من أنها تطبق Hashable.

• نسيت المُعدِل .focused() — @FocusState وحده لا يدير التركيز. يجب ربطه بحقل عبر .focused($property) أو .focused($property, equals: .case).
• عدة @FocusState في View واحد — لحقول متعددة، استخدم @FocusState واحد مع enum، وليس عدة خصائص @FocusState. عدة خصائص Bool لن تكون متزامنة مع بعضها البعض.
• تغيير @FocusState خارج السلك الرئيسي — يجب تغيير @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?