Formatter — ما هو، مُنسقات الإدخال و NSFormatter

ما هو Formatter في iOS؟

Formatter في iOS هو مكون يقوم بتحويل إدخال المستخدم الخام إلى تنسيق منظم وفقاً لنمط معين. على عكس التحقق البسيط بعد إرسال النموذج، يعمل المنسق في الوقت الفعلي، ويصحح عرض البيانات أثناء إدخالها. هذا هو الفرق الرئيسي: يرى المستخدم النتيجة المنسقة فوراً، دون الحاجة إلى إدخال الفواصل يدوياً.

يوفر iOS عدة مستويات تنسيق: منسقات النظام Foundation (NumberFormatter و DateFormatter و ByteCountFormatter) لعرض البيانات، وإطار عمل PhoneNumberKit لأرقام الهواتف، ومكتبات InputMask الخارجية لأقنعة الإدخال المخصصة. يعتمد اختيار المستوى على نوع البيانات ومرونة التنسيق المطلوبة.

وفقاً لـ Apple Human Interface Guidelines، تحل منسقات الإدخال ثلاث مهام: تقليل العبء المعرفي على المستخدم (لا حاجة للتفكير في الفواصل)، تقليل عدد الأخطاء (يتم إدخال البيانات بالتنسيق الصحيح)، وتسريع ملء النماذج (الانتقال التلقائي بين مجموعات الأرقام).

تعتبر المنسقات مهمة بشكل خاص لـ الأجهزة المحمولة، حيث يتطلب الإدخال بلوحة المفاتيح التي تظهر على الشاشة جهداً أكبر من اللوحة المادية. كل حرف إضافي يجب إدخاله يدوياً يزيد من وقت ملء النموذج وخطر الخطأ. يؤدي الإدراج التلقائي للفواصل إلى تقليل عدد اللمسات بنسبة 20–40% للتنسيقات النمطية.

أنواع مُنسقات الإدخال

تنقسم منسقات الإدخال في iOS إلى ثلاث فئات: منسقات النظام Foundation، ومنسقات Apple المتخصصة (PhoneNumberKit)، والمكتبات الخارجية (InputMask و MaskedTextField). كل فئة تحل مهامها الخاصة ولها خصائص تنفيذ مميزة.

منسقات النظام Foundation

NumberFormatter يقوم بتنسيق القيم الرقمية: المبالغ النقدية والنسب المئوية والترميزات العلمية. يدعم توطين فواصل المجموعات والفواصل العشرية. DateFormatter يحول التواريخ والأوقات إلى سلاسل محلية. هذه المنسقات مصممة للعرض وليس لإخفاء الإدخال، لذلك من الصعب تطبيقها مباشرة على UITextField أثناء الكتابة.

PhoneNumberKit

PhoneNumberKit هي مكتبة من Apple لتنسيق أرقام الهواتف وفقاً للمعايير الوطنية. تكتشف تلقائياً البلد عن طريق الرمز وتطبق التنسيق المقابل. على سبيل المثال، يتم تنسيق الرقم الروسي +7 912 345-67-89 بشكل مختلف عن الرقم الأمريكي +1 212-555-0198. يقوم PhoneNumberKit أيضاً بالتحقق من صحة الرقم.

مكتبات Input Mask

المكتبات الخارجية InputMask توفر آلية عالمية لإخفاء الإدخال لأي تنسيق: أرقام البطاقات (0000 0000 0000 0000)، التواريخ (DD.MM.YYYY)، SNILS (000-000-000 00)، INN (000000000000). تعمل المكتبات من خلال المفوض UITextFieldDelegate، حيث تعترض الإدخال وتطبق القناع في الوقت الفعلي.

الفئة المجردة NSFormatter

NSFormatter هي فئة مجردة من Foundation ترث منها جميع منسقات النظام في iOS. تحدد طريقتين رئيسيتين: string(for:) لتحويل كائن إلى سلسلة نصية و getObjectValue(_:for:errorDescription:) للتحويل العكسي من سلسلة إلى كائن. هذه الآلية ثنائية الاتجاه تسمح بعرض البيانات وقراءتها من حقول النص.

إنشاء منسق مخصص يعتمد على NSFormatter ممكن للتنسيقات المحددة غير المغطاة بفئات النظام. للقيام بذلك، يجب تجاوز طريقتَي string(for:) و getObjectValue(_:for:errorDescription:). يمكن استخدام المنسق المخصص مع UILabel و UITextField وعروض أخرى من خلال الخاصية formatter.

توصي Apple باستخدام منسقات Foundation الموجودة بدلاً من إنشاء منسقات مخصصة. يتعامل NumberFormatter بشكل صحيح مع 32 لغة ومعايير إقليمية، ويراعي DateFormatter التقاويم من ثقافات مختلفة، ويتبدل ByteCountFormatter تلقائياً بين البايت والكيلوبايت والميغابايت حسب حجم القيمة.

يدعم NSFormatter أيضاً توطين رسائل الخطأ للإدخال غير الصحيح. تقوم طريقة getObjectValue بإرجاع وصف للخطأ يمكن عرضه للمستخدم بشكل مترجم. هذا مهم بشكل خاص للنماذج حيث يدخل المستخدم بيانات بتنسيق غير صحيح — يجب أن تكون رسالة الخطأ مفهومة وبلغه الواجهة.

Input Mask وإخفاء الإدخال

Input Mask (قناع الإدخال) هو قالب يحدد تنسيق بيانات الإدخال ويدرج الفواصل تلقائياً أثناء الكتابة. يتكون القناع من أحرف نائبة (عادة 0 أو 9 للأرقام، A للحروف) وأحرف ثابتة (أقواس، شرطات، مسافات) يتم إدراجها تلقائياً. يدخل المستخدم الأحرف المهمة فقط، وتقوم النظام بإدراج الفواصل.

المكتبة الأكثر شهرة لنظام iOS هي InputMask من RedMadRobot. تدعم الأقنعة المعقدة مع الشروط والكتل الاختيارية واللواحق (بادئة ولاحقة). تم تنفيذ المكتبة من خلال مفوض، مما يسمح باستخدامها مع أي UITextField دون إنشاء فئة فرعية. يتم دعم الأقنعة لأرقام الهواتف والبطاقات المصرفية والتواريخ ورموز التأكيد والبيانات المنظمة الأخرى.

تنسيق قناع InputMask يستخدم بناء جملة خاصاً: أقواس مربعة للأحرف الإلزامية، وأقواس مجعدة للاختيارية، وأحرف ثابتة خارج الأقواس. على سبيل المثال، يبدو قناع رقم البطاقة كـ [0000] [0000] [0000] [0000]، وقناع التاريخ كـ [00]{.}[00]{.}[0000]. تختفي الكتل الاختيارية بين الأقواس المجعدة إذا لم يدخل المستخدم بيانات لها.

لـ أرقام الهواتف، يتضمن القناع عادة رمز البلد في اللاحقة: +7 ([000]) [000]-[00]-[00]. يدخل المستخدم 10 أرقام فقط من الرقم، بينما يتم إدراج الأحرف +7 و ( و ) و - تلقائياً. عند حرف حرف، يعالج القناع مفتاح المسح الخلفي بشكل صحيح، ويزيل آخر حرف مهم ويعود إلى الموضع السابق.

تنسيق أرقام الهواتف

تنسيق أرقام الهواتف هو حالة الاستخدام الأكثر شيوعاً للمنسقات في التطبيقات المحمولة. يوفر iOS إطار عمل PhoneNumberKit لهذا الغرض، والذي يحدد تلقائياً البلد عن طريق الرمز ويطبق التنسيق الوطني المقابل. تدعم المكتبة أكثر من 200 بلد ويتم تحديثها بانتظام.

يعمل PhoneNumberKit على مرحلتين: كشف التنسيق وتطبيقه. في المرحلة الأولى، تحلل المكتبة رمز البلد المُدخل (على سبيل المثال، +7 يحدد روسيا) وتحميل قواعد التنسيق. في المرحلة الثانية، تطبق قناعاً يتوافق مع المعيار الوطني: لروسيا هو +7 XXX XXX-XX-XX، للولايات المتحدة — +1 XXX-XXX-XXXX، للمملكة المتحدة — +44 XXXX XXX XXX.

وفقاً لـ Apple Developer Documentation، منذ iOS 16 ظهرت آلية مدمجة لتنسيق أرقام الهواتف من خلال UIContentUnavailableConfiguration. ومع ذلك، للتنسيق الكامل في الوقت الفعلي، يوصى باستخدام PhoneNumberKit من خلال مفوض UITextFieldDelegate. تقوم المكتبة أيضاً بالتحقق من صحة الرقم: تتحقق من عدد الأرقام وصلاحية رمز البلد والامتثال للتنسيق الوطني.

لـ التطبيقات الدولية، من المهم مراعاة أن المستخدم قد يدخل الرقم بأي تنسيق: مع +7 أو 8 (لروسيا) أو بدون رمز بلد. يجب أن يتعرف المنسق الجيد على أي تنسيق أولي ويطبيعه إلى معيار دولي موحد ببادئة + ورمز بلد.

تنفيذ المنسق في Swift

تنفيذ المنسق في Swift يعتمد على النهج المختار. لمنسقات النظام Foundation، تُستخدم الخاصية formatter المتاحة منذ iOS 15 لـ UITextField. لـ Input Mask، يُستخدم مفوض UITextFieldDelegate مع مكتبة InputMask. لأرقام الهواتف — PhoneNumberKit من خلال المفوض.

import PhoneNumberKit

class PhoneViewController: UIViewController {

    let phoneNumberKit = PhoneNumberKit()
    @IBOutlet var phoneField: UITextField!

    override func viewDidLoad() {
        super.viewDidLoad()
        phoneField.delegate = self
    }
}

extension PhoneViewController: UITextFieldDelegate {
    func textField(
        _ textField: UITextField,
        shouldChangeCharactersIn range: NSRange,
        replacementString string: String
    ) -> Bool {
        guard let text = textField.text else { return true }
        let partial = (text as NSString).replacingCharacters(in: range, with: string)
        textField.text = partial.applyPhoneMask()
        return false
    }
}

لـ NumberFormatter مع iOS 15+، الخاصية formatter متاحة على UITextField والتي تقوم بتنسيق الرقم المُدخل تلقائياً أثناء الكتابة. هذا النهج لا يتطلب تنفيذ مفوض ويعمل فورياً لتنسيقات العملات والنسب المئوية والبيانات الرقمية الأخرى مع مراعاة إعدادات المستخدم الإقليمية.

let amountField = UITextField()
let formatter = NumberFormatter()
formatter.numberStyle = .currency
formatter.locale = Locale(identifier: "ru_RU")
amountField.formatter = formatter

لـ مكتبة InputMask من RedMadRobot، يتم الإعداد من خلال تهيئة القناع والتطبيق عبر مفوض. تدعم المكتبة معالجة اللصق والحذف بالمسح الخلفي وتعمل بشكل صحيح مع تحديدات النص.

import InputMask

class CardViewController: UIViewController {
    @IBOutlet var cardField: UITextField!
    var listener: MaskedTextFieldDelegate!

    override func viewDidLoad() {
        super.viewDidLoad()
        listener = MaskedTextFieldDelegate(
            primaryMaskFormat: "[0000] [0000] [0000] [0000]"
        )
        cardField.delegate = listener
    }
}