UITextField — ما هو، إعداد حقل الإدخال ومبدأ العمل

ما هو UITextField

UITextField هو فئة من إطار عمل UIKit مصممة لإدخال النص بسطر واحد من قبل المستخدم. ترث الفئة من UIControl، مما يسمح بالاشتراك في أحداث الإدخال عبر آلية target-action: addTarget(self, action: Selector("textChanged:"), for: editingChanged). يعرض UITextField حداً (borderStyle) ونصاً placeholder عندما يكون الحقل فارغاً وزر مسح (clearButtonMode) ويمكن أن يحتوي على طرق عرض مساعدة يسار/يمين. يظهر/يخفي الحقل لوحة المفاتيح تلقائياً عند اكتساب/فقدان التركيز عبر becomeFirstResponder وresignFirstResponder. يتم تحديد حجم الحقل بواسطة intrinsicContentSize بناءً على الخط ونمط الحد. لإنشاء UITextField في Interface Builder (Storyboard/XIB)، استخدم مكتبة الكائنات؛ برمجياً، استخدم المُهيئ UITextField(frame: CGRect). الفئة متوافقة تماماً مع بنية iOS الحديثة: Combine publishers و@Published في SwiftUI عبر UIViewRepresentable وDiffable Data Source للنماذج.

أنواع لوحة المفاتيح UIKeyboardType

UITextField يدعم 12 نوعاً من لوحات المفاتيح عبر الخاصية keyboardType. كل نوع يحسن مجموعة الأحرف لسيناريو إدخال محدد. UIKeyboardType.default — لوحة مفاتيح QWERTY قياسية. UIKeyboardType.numberPad — أرقام فقط بدون رموز إضافية (مثالية لأكواد PIN وأرقام الهواتف). UIKeyboardType.emailAddress — لوحة مفاتيح مع @ ونقطة على الطبقة الرئيسية. UIKeyboardType.URL — لوحة مفاتيح مع .com و / ونقطة على الطبقة الرئيسية. UIKeyboardType.phonePad — لوحة مفاتيح رقمية مع + و * و # لإدخال أرقام الهواتف. UIKeyboardType.decimalPad — أرقام مع نقطة عشرية لإدخال الأسعار. UIKeyboardType.webSearch — لوحة مفاتيح مع زر Go محسنة لاستعلامات البحث. UIKeyboardType.asciiCapable — أحرف ASCII فقط للنص اللاتيني. تظهر لوحة المفاتيح عند استدعاء becomeFirstResponder وتختفي عند استدعاء resignFirstResponder. يمكن تغيير نوع لوحة المفاتيح ديناميكياً أثناء التحرير.

المفوض UITextFieldDelegate وطرقه

UITextFieldDelegate هو بروتوكول يحدد سلوك حقل النص في مراحل مختلفة من الإدخال. الطرق الرئيسية: textFieldShouldBeginEditing(textField) — يُرجع Bool يسمح أو يمنع بدء التحرير؛ textFieldDidBeginEditing — يُستدعى بعد ظهور لوحة المفاتيح؛ textFieldShouldEndEditing — يتحقق مما إذا كان يمكن إكمال التحرير (إذا كان false، لا يفقد الحقل التركيز)؛ textFieldDidEndEditing — يُستدعى بعد إخفاء لوحة المفاتيح؛ textFieldShouldChangeCharactersInRange — يُستدعى عند كل إدخال حرف، يسمح بتصفية الإدخال (يُسمح بحرف واحد فقط، إذا تم إرجاع false، لا يُضاف الحرف)؛ textFieldShouldReturn — يُستدعى عند الضغط على Return/Go/Next/Search، يُستخدم للانتقال إلى الحقل التالي. المفوض ليس Optional: جميع الطرق لها تطبيق افتراضي، ولكن للسلوك المخصص تحتاج إلى تجاوز الطريقة المقابلة.

إدارة التركيز عبر shouldReturn

طريقة shouldReturn هي النمط القياسي للتنقل بين حقول النموذج. التطبيق: textFieldShouldReturn(textField) — تحقق من أي textField أثار الحدث وانقل التركيز إلى الحقل التالي عبر becomeFirstResponder(). إذا كان الحقل الأخير، استدع resignFirstResponder() لإخفاء لوحة المفاتيح. استخدم IBOutlet collection أو IBOutlets منفصلة لكل حقل لتخزين مراجع الحقول.

Secure Text Entry وطرق العرض left/right المخصصة

isSecureTextEntry — خاصية UITextField التي، عندما تكون true، تستبدل الأحرف المدخلة بنقاط (•) وتمنع نسخ النص عبر UIMenuController. تُستخدم لحقول كلمة المرور وأكواد PIN وCVV. عند التبديل بين الوضع الآمن والنص العادي (show/hide password)، قم بتعيين textField.isSecureTextEntry.toggle(). مهم: عند تغيير isSecureTextEntry، يتم إعادة تعيين نص الحقل — احفظه مسبقاً. LeftView و RightView هما UIView مخصصان يُعرضان داخل حقل الإدخال على اليسار أو اليمين. الاستخدام النموذجي: أيقونة بحث في leftView، زر "مسح" في rightView. التكوين: textField.leftViewMode = always (دائماً) أو whileEditing (أثناء التحرير فقط). يتم وضع طرق العرض left/right تلقائياً داخل حقل النص مع مراعاة الحشو. يتم تعيين حجم العرض عبر bounds أو Auto Layout.

import UIKit

class LoginViewController: UIViewController {
    let passwordField = UITextField()

    override func viewDidLoad() {
        super.viewDidLoad()
        passwordField.isSecureTextEntry = true
        passwordField.placeholder = "Password"
        passwordField.keyboardType = .asciiCapable
        passwordField.delegate = self

        // زر مخصص لإظهار/إخفاء كلمة المرور
        let showButton = UIButton(type: .system)
        showButton.setTitle("إظهار", for: .normal)
        showButton.addTarget(self, action: #selector(togglePasswordVisibility),
                       for: .touchUpInside)
        passwordField.rightView = showButton
        passwordField.rightViewMode = .always
    }

    @objc func togglePasswordVisibility() {
        passwordField.isSecureTextEntry.toggle()
    }
}

تكوين UITextInputTraits

UITextInputTraits هو بروتوكول يحدد المظهر المرئي والسلوكي للوحة المفاتيح لـ UITextField. الخصائص الرئيسية: autocorrectionType (.default, .no, .yes) — يقوم بتشغيل أو إيقاف التصحيح التلقائي للنص؛ autocapitalizationType (.none, .words, .sentences, .allCharacters) — قفل تلقائي للأحرف الكبيرة للحرف الأول؛ spellCheckingType — التدقيق الإملائي؛ returnKeyType (.done, .go, .next, .search, .send, .continue, .join, .route, .emergencyCall) — نص زر Return على لوحة المفاتيح؛ enablesReturnKeyAutomatically — قفل تلقائي لزر Return عندما يكون الحقل فارغاً. لحقول إدخال الاسم، استخدم autocapitalizationType = .words؛ للبريد الإلكتروني، استخدم autocorrectionType = .no؛ لعنوان URL، استخدم keyboardType = .URL + autocapitalizationType = .none. يتم تكوين الخصائص بعد تهيئة الحقل قبل عرضه. تغيير الخصائص ديناميكياً يحدث لوحة المفاتيح عند ظهورها التالي.

Return Key Type والتنقل في النموذج

Return Key Type يحدد نص الزر على لوحة المفاتيح: Next — الانتقال إلى الحقل التالي، Done — إكمال الإدخال، Search — بدء البحث، Send — إرسال النموذج، Continue — متابعة التعبئة. بالاقتران مع طريقة المفوض shouldReturn، يسمح returnKeyType بتجربة مستخدم طبيعية: يملأ المستخدم الحقول، ويضغط Next للانتقال إلى التالي، وDone للإرسال في الحقل الأخير. لتخصيص نص الزر، استخدم UIButtonConfiguration في iOS 15+.

Placeholder والتنسيق وقناع الإدخال

Placeholder UITextField هو النص المعروض باللون الرمادي عندما يكون الحقل فارغاً. التكوين: textField.placeholder = "Enter email". لتخصيص لون placeholder وخطه، استخدم attributedPlaceholder مع NSAttributedString. قناع الإدخال يتم تنفيذه عبر طريقة المفوض shouldChangeCharactersInRange — يدعم تنسيق رقم الهاتف والتاريخ وبطاقة الائتمان وSNILS. يسمح قناع الإدخال بفصل العرض عن القيمة: يرى المستخدم نصاً منسقاً (مثل +7 (999) 999-99-99)، بينما يخزن النموذج "79999999999". مثال للتطبيق: خزن القناع كسلسلة بأحرف X للاستبدال؛ عند كل إدخال، شكل السلسلة المنسقة وأرجع false في shouldChangeCharactersInRange، مستبدلاً نص الحقل عبر textField.text = formattedText. للأرقام، استخدم NumberFormatter وkeyboardType العشري.

extension LoginViewController: UITextFieldDelegate {
    func textFieldShouldReturn(
        textField: UITextField
    ) -> Bool {
        if textField == emailField {
            passwordField.becomeFirstResponder()
        } else if textField == passwordField {
            textField.resignFirstResponder()
            loginTapped()
        }
        return true
    }

    func textField(
        textField: UITextField,
        shouldChangeCharactersIn range: NSRange,
        replacementString string: String
    ) -> Bool {
        // منع المسافات في البريد الإلكتروني
        if textField == emailField && string == " " {
            return false
        }
        // حد طول كلمة المرور
        if textField == passwordField {
            let newLength = (textField.text?.count ?? 0) +
                string.count - range.length
            return newLength <= 32
        }
        return true
    }
}

أمثلة كود: التحقق من الصحة والنموذج

لنلق نظرة على مثال كامل لتطبيق نموذج تسجيل دخول بـ UITextField مع التحقق من صحة البريد الإلكتروني وتغذية راجعة بصرية. يحتوي النموذج على حقلين: emailField (لوحة مفاتيح emailAddress، بدون تصحيح تلقائي) وpasswordField (secureTextEntry). يتم التحقق في shouldChangeCharactersInRange وإضافياً عند الضغط على زر Login. للتغذية الراجعة البصرية: حد أحمر (layer.borderColor) عند الخطأ، أخضر — عند التحقق الناجح. إعادة تعيين الحد عند بدء التحرير في textFieldDidBeginEditing.

التحقق من صحة البريد الإلكتروني بتعبير منتظم

التحقق من صحة البريد الإلكتروني يتم عبر NSPredicate بالتنسيق "SELF MATCHES %@" وتعبير منتظم للتحقق الأساسي من التنسيق. يجب إجراء التحقق الفعلي من وجود البريد الإلكتروني على الخادم. للتحقق المتقدم، استخدم مكتبة SwiftValidators أو Combine publishers. مثال: NSPredicate(format: "SELF MATCHES [c] %@", emailRegex).evaluate(with: email). يتم تحديث حد الحقل عبر كتلة رسوم متحركة لانتقال سلس.

func validateEmail(textField: UITextField) {
    guard let text = textField.text, !text.isEmpty else {
        textField.layer.borderColor = UIColor.clear.cgColor
        return
    }

    let emailRegex = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.\\p{L}{2,}"
    let predicate = NSPredicate(format: "SELF MATCHES [c] %@", emailRegex)
    let isValid = predicate.evaluate(with: text)

    UIView.animate(withDuration: 0.2) {
        textField.layer.borderColor = isValid
            ? UIColor.systemGreen.cgColor
            : UIColor.systemRed.cgColor
        textField.layer.borderWidth = 1.0
        textField.layer.cornerRadius = 6.0
    }
}