UITextField — چیست، تنظیمات فیلد ورودی و اصل کار

UITextField چیست

UITextField — کلاسی از فریمورک UIKit است که برای ورود متن تک خطی توسط کاربر طراحی شده است. این کلاس از UIControl ارث‌بری می‌کند که امکان اشتراک در رویدادهای ورودی را از طریق مکانیزم target-action فراهم می‌کند: addTarget(self, action: Selector("textChanged:"), for: editingChanged). UITextField حاشیه (borderStyle)، متن placeholder در حالت خالی، دکمه پاک کردن (clearButtonMode) را نمایش می‌دهد و می‌تواند دارای viewهای کمکی چپ/راست باشد. فیلد به طور خودکار با becomeFirstResponder و resignFirstResponder صفحه کلید را نمایش/مخفی می‌کند. اندازه فیلد توسط intrinsicContentSize بر اساس font و border style تعیین می‌شود. برای ایجاد UITextField در Interface Builder (Storyboard/XIB) از Object Library استفاده می‌شود، به صورت برنامه‌نویسی — از طریق مقداردهنده UITextField(frame: CGRect). این کلاس کاملاً با معماری مدرن iOS سازگار است: Combine publishers، @Published در SwiftUI از طریق UIViewRepresentable و Diffable Data Source برای فرم‌ها.

انواع صفحه کلید UIKeyboardType

UITextField از ۱۲ نوع صفحه کلید از طریق ویژگی keyboardType پشتیبانی می‌کند. هر نوع مجموعه کاراکترها را برای سناریوی ورودی خاصی بهینه می‌کند. UIKeyboardType.default — صفحه کلید استاندارد QWERTY. UIKeyboardType.numberPad — فقط اعداد بدون کاراکترهای اضافی (ایده‌آل برای PIN و شماره تلفن). UIKeyboardType.emailAddress — صفحه کلید با کاراکتر @ و نقطه در لایه اصلی. UIKeyboardType.URL — صفحه کلید با .com، / و . در لایه اصلی. UIKeyboardType.phonePad — صفحه کلید عددی با +، *، # برای وارد کردن شماره تلفن. UIKeyboardType.decimalPad — اعداد با نقطه اعشاری برای وارد کردن قیمت. UIKeyboardType.webSearch — صفحه کلید با دکمه Go و بهینه‌سازی برای جستجو. UIKeyboardType.asciiCapable — فقط کاراکترهای ASCII برای الفبای لاتین. صفحه کلید با فراخوانی becomeFirstResponder نمایش داده می‌شود و با resignFirstResponder مخفی می‌شود. نوع صفحه کلید را می‌توان به صورت پویا در طول ویرایش تغییر داد.

Delegate UITextFieldDelegate و متدهای آن

UITextFieldDelegate — پروتکلی است که رفتار فیلد متنی را در مراحل مختلف ورودی تعریف می‌کند. متدهای اصلی: textFieldShouldBeginEditing(textField) — مقدار Bool برمی‌گرداند که اجازه یا ممنوعیت شروع ویرایش را مشخص می‌کند; textFieldDidBeginEditing — پس از نمایش صفحه کلید فراخوانی می‌شود; textFieldShouldEndEditing — بررسی می‌کند که آیا ویرایش می‌تواند پایان یابد (در صورت false فیلد focus را از دست نمی‌دهد); textFieldDidEndEditing — پس از مخفی شدن صفحه کلید فراخوانی می‌شود; textFieldShouldChangeCharactersInRange — با هر ورود کاراکتر فراخوانی می‌شود، امکان فیلتر کردن ورودی را فراهم می‌کند (فقط یک کاراکتر مجاز است، اگر false برگرداند کاراکتر اضافه نمی‌شود); textFieldShouldReturn — هنگام فشار دادن Return/Go/Next/Search فراخوانی می‌شود، برای انتقال به فیلد بعدی استفاده می‌شود. Delegate از نوع Optional نیست: همه متدها پیاده‌سازی پیش‌فرض دارند، اما برای رفتار سفارشی باید متد مربوطه را override کرد.

مدیریت focus از طریق shouldReturn

متد shouldReturn — الگوی استاندارد برای پیمایش بین فیلدهای فرم. پیاده‌سازی: textFieldShouldReturn(textField) — بررسی می‌کنیم کدام textField رویداد را فراخوانی کرده و focus را به فیلد بعدی از طریق becomeFirstResponder() منتقل می‌کنیم. اگر این آخرین فیلد باشد — برای مخفی کردن صفحه کلید resignFirstResponder() را فراخوانی می‌کنیم. برای ذخیره ارجاع به فیلدها از IBOutlet collection یا IBOutlet جداگانه برای هر فیلد استفاده کنید.

Secure Text Entry و left/right view سفارشی

isSecureTextEntry — ویژگی UITextField که در صورت true کاراکترهای وارد شده را با نقطه (•) جایگزین می‌کند و کپی کردن متن را از طریق UIMenuController مسدود می‌کند. برای فیلدهای رمز عبور، PIN، CVV استفاده می‌شود. هنگام جابجایی بین حالت secure و متن معمولی (show/hide password) textField.isSecureTextEntry.toggle() را تنظیم کنید. مهم: هنگام تغییر isSecureTextEntry متن فیلد بازنشانی می‌شود — آن را از قبل ذخیره کنید. LeftView و RightView — UIViewهای سفارشی هستند که در داخل فیلد ورودی در سمت چپ یا راست نمایش داده می‌شوند. استفاده معمول: آیکون جستجو در leftView، دکمه "پاک کردن" در rightView. تنظیمات: textField.leftViewMode = always (همیشه) یا whileEditing (فقط هنگام ویرایش). Left/right view به طور خودکار در داخل فیلد متنی با در نظر گرفتن padding قرار می‌گیرند. اندازه view توسط 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) — Caps Lock خودکار برای اولین کاراکتر; spellCheckingType — بررسی املا; returnKeyType (.done, .go, .next, .search, .send, .continue, .join, .route, .emergencyCall) — متن دکمه Return روی صفحه کلید; enablesReturnKeyAutomatically — مسدود کردن خودکار دکمه Return در صورت خالی بودن فیلد. برای فیلدهای ورود نام از autocapitalizationType = .words، برای ایمیل — autocorrectionType = .no، برای URL — keyboardType = .URL + autocapitalizationType = .none استفاده کنید. تنظیم traits پس از مقداردهی فیلد و قبل از نمایش آن انجام می‌شود. تغییر traits صفحه کلید را در نمایش بعدی به صورت پویا به‌روزرسانی می‌کند.

Return Key Type و پیمایش در فرم

Return Key Type متن دکمه روی صفحه کلید را تعیین می‌کند: Next — رفتن به فیلد بعدی، Done — پایان ورود، Search — شروع جستجو، Send — ارسال فرم، Continue — ادامه پر کردن. در ترکیب با متد delegate shouldReturn، returnKeyType امکان ایجاد UX طبیعی را فراهم می‌کند: کاربر فیلدها را پر می‌کند، Next را برای رفتن به فیلد بعدی و Done را برای ارسال در آخرین فیلد فشار می‌دهد. برای سفارشی‌سازی متن دکمه از UIButtonConfiguration در iOS 15+ استفاده کنید.

Placeholder، قالب‌بندی و ماسک ورودی

Placeholder UITextField — متنی است که با رنگ خاکستری وقتی فیلد خالی است نمایش داده می‌شود. تنظیمات: textField.placeholder = "Enter email". برای سفارشی‌سازی رنگ و فونت placeholder از attributedPlaceholder با NSAttributedString استفاده کنید. ماسک ورودی از طریق متد delegate shouldChangeCharactersInRange پیاده‌سازی می‌شود — فرمت شماره تلفن، تاریخ، کارت اعتباری، SNILS پشتیبانی می‌شود. ماسک ورودی امکان جداسازی نمایش و مقدار را فراهم می‌کند: کاربر متن قالب‌بندی شده را می‌بیند (مثلاً +7 (999) 999-99-99)، و در مدل "79999999999" ذخیره می‌شود. مثال پیاده‌سازی: ماسک را به عنوان رشته‌ای با کاراکترهای X برای جایگزینی ذخیره می‌کنیم; در هر ورود رشته قالب‌بندی شده را ایجاد می‌کنیم و در shouldChangeCharactersInRange false برمی‌گردانیم، متن فیلد را از طریق textField.text = formattedText جایگزین می‌کنیم. برای اعداد از NumberFormatter و decimal 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). حاشیه فیلد از طریق animation block برای انتقال روان به‌روزرسانی می‌شود.

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