Formatter — cos’è, formattatori di input e NSFormatter

Cos’è Formatter in iOS?

Formatter in iOS è un componente che converte l’input grezzo dell’utente in un formato strutturato secondo un modello specificato. A differenza della semplice validazione dopo l’invio del modulo, un formattatore funziona in tempo reale, correggendo la visualizzazione dei dati mentre vengono inseriti. Questa è la differenza fondamentale: l’utente vede il risultato formattato immediatamente, senza dover inserire manualmente i separatori.

iOS offre diversi livelli di formattazione: formattatori di sistema Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) per la visualizzazione dei dati, il framework PhoneNumberKit per i numeri di telefono e librerie di terze parti InputMask per maschere di input personalizzate. La scelta del livello dipende dal tipo di dati e dalla flessibilità di formattazione richiesta.

Secondo le Apple Human Interface Guidelines, i formattatori di input risolvono tre compiti: riducono il carico cognitivo dell’utente (senza dover pensare ai separatori), diminuiscono il numero di errori (i dati vengono inseriti nel formato corretto) e accelerano la compilazione dei moduli (transizione automatica tra gruppi di cifre).

I formattatori sono particolarmente importanti per i dispositivi mobili, dove l’input con tastiera virtuale richiede più sforzo rispetto a una fisica. Ogni carattere extra da inserire manualmente aumenta il tempo di compilazione del modulo e il rischio di errore. L’inserimento automatico dei separatori riduce il numero di tocchi del 20–40% per i formati tipici.

Tipi di formattatori di input

I formattatori di input in iOS si dividono in tre categorie: formattatori di sistema Foundation, formattatori specializzati Apple (PhoneNumberKit) e librerie di terze parti (InputMask, MaskedTextField). Ogni categoria risolve i propri compiti e ha particolarità di implementazione.

Formattatori di sistema Foundation

NumberFormatter formatta valori numerici: importi monetari, percentuali, notazioni scientifiche. Supporta la localizzazione dei separatori di gruppo e decimali. DateFormatter converte date e orari in stringhe localizzate. Questi formattatori sono progettati per la visualizzazione, non per il mascheramento dell’input, quindi sono difficili da applicare direttamente a UITextField durante la digitazione.

PhoneNumberKit

PhoneNumberKit è una libreria Apple per formattare i numeri di telefono secondo gli standard nazionali. Rileva automaticamente il paese dal prefisso e applica il formato corrispondente. Ad esempio, un numero russo +7 912 345-67-89 viene formattato diversamente da uno americano +1 212-555-0198. PhoneNumberKit valida anche la correttezza del numero.

Librerie Input Mask

Le librerie di terze parti InputMask forniscono un meccanismo universale di mascheramento dell’input per qualsiasi formato: numeri di carta (0000 0000 0000 0000), date (DD.MM.AAAA), SNILS (000-000-000 00), INN (000000000000). Le librerie funzionano tramite il delegato UITextFieldDelegate, intercettando l’input e applicando la maschera in tempo reale.

Classe astratta NSFormatter

NSFormatter è una classe astratta di Foundation da cui ereditano tutti i formattatori di sistema iOS. Definisce due metodi principali: string(for:) per convertire un oggetto in stringa e getObjectValue(_:for:errorDescription:) per la conversione inversa da stringa a oggetto. Questo meccanismo bidirezionale consente sia di visualizzare i dati che di leggerli dai campi di testo.

La creazione di un formattatore personalizzato basato su NSFormatter è possibile per formati specifici non coperti dalle classi di sistema. Per farlo, è necessario sovrascrivere i metodi string(for:) e getObjectValue(_:for:errorDescription:). Un formattatore personalizzato può essere utilizzato con UILabel, UITextField e altre viste tramite la proprietà formatter.

Apple raccomanda di utilizzare i formattatori Foundation esistenti invece di crearne di personalizzati. NumberFormatter gestisce correttamente 32 lingue e standard regionali, DateFormatter tiene conto dei calendari di diverse culture, e ByteCountFormatter passa automaticamente tra byte, kilobyte e megabyte in base alla dimensione del valore.

NSFormatter supporta anche la localizzazione dei messaggi di errore per input non corretti. Il metodo getObjectValue restituisce una descrizione dell’errore che può essere mostrata all’utente in forma localizzata. Ciò è particolarmente importante per i moduli in cui l’utente inserisce dati in un formato errato — il messaggio di errore deve essere comprensibile e nella lingua dell’interfaccia.

Input Mask e mascheramento dell’input

Input Mask (maschera di input) è un modello che definisce il formato dei dati di input e inserisce automaticamente i separatori durante la digitazione. La maschera è composta da caratteri segnaposto (solitamente 0 o 9 per le cifre, A per le lettere) e caratteri costanti (parentesi, trattini, spazi) che vengono inseriti automaticamente. L’utente inserisce solo i caratteri significativi, mentre i separatori vengono inseriti dal sistema.

La libreria più popolare per iOS è InputMask di RedMadRobot. Supporta maschere complesse con condizioni, blocchi opzionali e affissi (prefisso e suffisso). La libreria è implementata tramite un delegato, consentendone l’uso con qualsiasi UITextField senza subclassing. Sono supportate maschere per numeri di telefono, carte bancarie, date, codici di conferma e altri dati strutturati.

Il formato della maschera InputMask utilizza una sintassi propria: parentesi quadre per i caratteri obbligatori, parentesi graffe per quelli opzionali, caratteri costanti fuori dalle parentesi. Ad esempio, una maschera per numero di carta appare come [0000] [0000] [0000] [0000], e per la data — [00]{.}[00]{.}[0000]. I blocchi opzionali tra parentesi graffe scompaiono se l’utente non inserisce dati per essi.

Per i numeri di telefono, la maschera include solitamente il prefisso del paese nell’affisso: +7 ([000]) [000]-[00]-[00]. L’utente inserisce solo 10 cifre del numero, mentre i caratteri +7, (, ), - vengono inseriti automaticamente. Quando si elimina un carattere, la maschera gestisce correttamente il backspace, rimuovendo l’ultimo carattere significativo e tornando alla posizione precedente.

Formattazione dei numeri di telefono

La formattazione dei numeri di telefono è il caso d’uso più comune dei formattatori nelle applicazioni mobili. iOS fornisce il framework PhoneNumberKit a questo scopo, che determina automaticamente il paese dal prefisso e applica il formato nazionale corrispondente. La libreria supporta oltre 200 paesi e viene aggiornata regolarmente.

PhoneNumberKit funziona in due fasi: rilevamento del formato e sua applicazione. Nella prima fase, la libreria analizza il prefisso del paese inserito (ad esempio, +7 identifica la Russia) e carica le regole di formattazione. Nella seconda fase, applica una maschera corrispondente allo standard nazionale: per la Russia è +7 XXX XXX-XX-XX, per gli Stati Uniti — +1 XXX-XXX-XXXX, per il Regno Unito — +44 XXXX XXX XXX.

Secondo la documentazione Apple Developer, da iOS 16 è apparso un meccanismo integrato di formattazione dei numeri di telefono tramite UIContentUnavailableConfiguration. Tuttavia, per una formattazione completa in tempo reale, si consiglia di utilizzare PhoneNumberKit attraverso il delegato UITextFieldDelegate. La libreria valida anche il numero: verifica il numero di cifre, la validità del prefisso del paese e la conformità al formato nazionale.

Per le applicazioni internazionali, è importante considerare che l’utente potrebbe inserire il numero in qualsiasi formato: con +7, 8 (per la Russia) o senza prefisso del paese. Un buon formattatore deve riconoscere qualsiasi formato iniziale e normalizzarlo a uno standard internazionale unico con prefisso + e codice del paese.

Implementazione del formattatore in Swift

L’implementazione del formattatore in Swift dipende dall’approccio scelto. Per i formattatori di sistema Foundation, si utilizza la proprietà formatter, disponibile da iOS 15 per UITextField. Per Input Mask, si utilizza il delegato UITextFieldDelegate con la libreria InputMask. Per i numeri di telefono — PhoneNumberKit tramite il delegato.

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

Per NumberFormatter con iOS 15+, la proprietà formatter è disponibile su UITextField e formatta automaticamente il numero inserito durante la digitazione. Questo approccio non richiede l’implementazione di un delegato e funziona immediatamente per formati di valuta, percentuali e altri dati numerici tenendo conto delle impostazioni regionali dell’utente.

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

Per la libreria InputMask di RedMadRobot, la configurazione avviene tramite inizializzazione della maschera e applicazione tramite un delegato. La libreria supporta la gestione dell’incolla, l’eliminazione con backspace e funziona correttamente con le selezioni di testo.

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