Formatter — ce este, formatatoare de intrare și NSFormatter

Ce este Formatter în iOS?

Formatter în iOS este o componentă care transformă intrarea brută a utilizatorului într-un format structurat conform unui șablon specificat. Spre deosebire de validarea simplă după trimiterea formularului, formatatorul lucrează în timp real, corectând afișarea datelor pe măsură ce acestea sunt introduse. Aceasta este diferența cheie: utilizatorul vede rezultatul formatat imediat, fără a fi nevoie să introducă manual separatoarele.

iOS oferă mai multe niveluri de formatare: formatatoarele de sistem Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) pentru afișarea datelor, framework-ul PhoneNumberKit pentru numere de telefon și bibliotecile terțe InputMask pentru măști de intrare arbitrare. Alegerea nivelului depinde de tipul de date și de flexibilitatea de formatare necesară.

Conform Apple Human Interface Guidelines, formatatoarele de intrare rezolvă trei sarcini: reduc încărcătura cognitivă a utilizatorului (nu trebuie să se gândească la separatoare), reduc numărul de erori (datele sunt introduse în format corect) și accelerează completarea formularelor (trecerea automată între grupurile de cifre).

Formatatoarele sunt deosebit de importante pentru dispozitivele mobile, unde introducerea datelor cu tastatura pe ecran necesită mai mult efort decât cu una fizică. Fiecare caracter suplimentar care trebuie introdus manual crește timpul de completare a formularului și riscul de eroare. Înlocuirea automată a separatorelor reduce numărul de atingeri cu 20–40% pentru formatele tipice.

Tipuri de formatatoare de intrare

Formatatoarele de intrare în iOS se împărt în trei categorii: formatatoarele de sistem Foundation, formatatoarele specializate Apple (PhoneNumberKit) și bibliotecile terțe (InputMask, MaskedTextField). Fiecare categorie își rezolvă propriile sarcini și are caracteristici specifice de implementare.

Formatatoarele de sistem Foundation

NumberFormatter formatează valorile numerice: sume monetare, procente, notații științifice. Suportă localizarea separatorelor de grup și a semnelor zecimale. DateFormatter convertește datele și ora în șiruri localizate. Aceste formatatoare sunt destinate afișării, nu mascării intrării, de aceea este dificil să fie aplicate direct la UITextField în timpul tastării.

PhoneNumberKit

PhoneNumberKit — biblioteca Apple pentru formatarea numerelor de telefon conform standardelor naționale. Aceasta detectează automat țara pe baza codului și aplică formatul corespunzător. De exemplu, numărul rusesc +7 912 345-67-89 este formatat diferit față de cel american +1 212-555-0198. PhoneNumberKit validează și corectitudinea numărului.

Bibliotecile Input Mask

Bibliotecile terțe InputMask oferă un mecanism universal de mascare a intrării pentru orice format: numere de card (0000 0000 0000 0000), date (ZZ.LL.AAAA), CNP (0000000000000). Bibliotecile funcționează prin delegatul UITextFieldDelegate, interceptând intrarea și aplicând masca în timp real.

Clasa abstractă NSFormatter

NSFormatter — este o clasă abstractă Foundation de care moștenesc toate formatatoarele de sistem iOS. Aceasta definește două metode principale: string(for:) pentru transformarea obiectului în șir și getObjectValue(_:for:errorDescription:) pentru transformarea inversă a șirului în obiect. Acest mecanism bidirecțional permite atât afișarea datelor, cât și citirea acestora din câmpuri de text.

Crearea unui formatator propriu bazat pe NSFormatter este posibilă pentru formate specifice neacoperite de clasele de sistem. Pentru aceasta, trebuie suprascrise metodele string(for:) și getObjectValue(_:for:errorDescription:). Formatatorul propriu poate fi utilizat cu UILabel, UITextField și alte view-uri prin proprietatea formatter.

Apple recomandă utilizarea formatatoarelor existente Foundation în locul creării unora proprii. NumberFormatter procesează corect 32 de limbi și standarde regionale, DateFormatter ține cont de calendarele diferitelor culturi, iar ByteCountFormatter comută automat între bytes, kilobytes și megabytes în funcție de valoare.

NSFormatter suportă și localizarea mesajelor de eroare la introducerea incorectă. Metoda getObjectValue returnează o descriere a erorii care poate fi afișată utilizatorului într-o formă localizată. Acest lucru este deosebit de important în formularele unde utilizatorul introduce date într-un format greșit — mesajul de eroare trebuie să fie clar și în limba interfeței.

Input Mask și mascarea intrării

Input Mask (masca de intrare) — este un șablon care definește formatul datelor introduse și plasează automat separatoarele pe măsură ce se tastează. Masca constă din caractere de substituție (de obicei 0 sau 9 pentru cifre, A pentru litere) și caractere constante (paranteze, cratime, spații) care sunt inserate automat. Utilizatorul introduce doar caracterele semnificative, iar separatoarele sunt plasate de sistem.

Cea mai populară bibliotecă pentru iOS — InputMask de la RedMadRobot. Suportă măști complexe cu condiții, blocuri opționale și afix (prefix și sufix). Biblioteca este implementată prin delegat, ceea ce permite utilizarea sa cu orice UITextField fără subclassing. Sunt suportate măști pentru numere de telefon, carduri bancare, date, coduri de confirmare și alte date structurate.

Formatul măștii InputMask folosește sintaxa proprie: paranteze drepte pentru caractere obligatorii, acolade pentru cele opționale, caractere constante în afara parantezelor. De exemplu, masca pentru numărul de card arată ca [0000] [0000] [0000] [0000], iar pentru dată — [00]{.}[00]{.}[0000]. Blocurile opționale în acolade dispar dacă utilizatorul nu introduce date pentru ele.

Pentru numerele de telefon masca include de obicei codul țării în afix: +7 ([000]) [000]-[00]-[00]. Utilizatorul introduce doar 10 cifre ale numărului, iar caracterele +7, (, ), - sunt inserate automat. La ștergerea unui caracter, masca procesează corect backspace, eliminând ultimul caracter semnificativ și revenind la poziția anterioară.

Formatarea numerelor de telefon

Formatarea numerelor de telefon — este cel mai frecvent scenariu de utilizare a formatatoarelor în aplicațiile mobile. iOS oferă în acest scop framework-ul PhoneNumberKit, care detectează automat țara pe baza codului și aplică formatul național corespunzător. Biblioteca suportă peste 200 de țări și este actualizată regulat.

PhoneNumberKit funcționează în două etape: detectarea formatului și aplicarea acestuia. În prima etapă, biblioteca analizează codul de țară introdus (de exemplu, +7 detectează Rusia) și încarcă regulile de formatare. În a doua etapă, aplică masca corespunzătoare standardului național: pentru Rusia - +7 XXX XXX-XX-XX, pentru SUA — +1 XXX-XXX-XXXX, pentru Marea Britanie — +44 XXXX XXX XXX.

Conform Apple Developer Documentation, începând cu iOS 16 a apărut un mecanism încorporat de formatare a numerelor de telefon prin UIContentUnavailableConfiguration. Cu toate acestea, pentru formatarea completă în timp real se recomandă utilizarea PhoneNumberKit prin delegatul UITextFieldDelegate. Biblioteca validează și numărul: verifică numărul de cifre, admisibilitatea codului de țară și conformitatea cu formatul național.

Pentru aplicațiile internaționale este important să se țină cont că utilizatorul poate introduce numărul în orice format: cu +7, 8 (pentru Rusia) sau fără cod de țară. Un formatator bun trebuie să recunoască orice format inițial și să îl normalizeze la un standard internațional unic cu prefixul + și codul de țară.

Implementarea formatatorului în Swift

Implementarea formatatorului în Swift depinde de abordarea aleasă. Pentru formatatoarele de sistem Foundation se utilizează proprietatea formatter disponibilă din iOS 15 pentru UITextField. Pentru Input Mask se utilizează delegatul UITextFieldDelegate cu biblioteca InputMask. Pentru numerele de telefon — PhoneNumberKit prin delegat.

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

Pentru NumberFormatter din iOS 15+ este disponibilă proprietatea formatter pe UITextField, care formatează automat numărul introdus pe măsură ce se tastează. Această abordare nu necesită implementarea delegatului și funcționează „cutie” pentru formate monetare, procente și alte date numerice ținând cont de localizarea utilizatorului.

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

Pentru biblioteca InputMask RedMadRobot configurarea se face prin inițializarea măștii și aplicarea prin delegat. Biblioteca suportă inserarea (paste), ștergerea (backspace) și funcționează corect cu selecțiile de text.

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