Formatter — co to, formatery wejścia i NSFormatter

Co to jest Formatter w iOS?

Formatter w iOS — to komponent, który przekształca nieprzetworzone dane wejściowe użytkownika w strukturyzowany format zgodnie z określonym wzorem. W przeciwieństwie do prostej walidacji po wysłaniu formularza, formater działa w czasie rzeczywistym, korygując wyświetlanie danych w miarę ich wprowadzania. To kluczowa różnica: użytkownik widzi sformatowany wynik od razu, bez potrzeby ręcznego wprowadzania separatorów.

iOS zapewnia kilka poziomów formatowania: systemowe formatery Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) do wyświetlania danych, framework PhoneNumberKit do numerów telefonów i biblioteki zewnętrzne InputMask do dowolnych masek wprowadzania. Wybór poziomu zależy od typu danych i wymaganej elastyczności formatowania.

Według Apple Human Interface Guidelines, formatery wprowadzania rozwiązują trzy zadania: zmniejszają obciążenie poznawcze użytkownika (nie trzeba myśleć o separatorach), redukują liczbę błędów (dane są wprowadzane w poprawnym formacie) i przyspieszają wypełnianie formularzy (automatyczne przechodzenie między grupami cyfr).

Formatery są szczególnie ważne dla urządzeń mobilnych, gdzie wprowadzanie danych z ekranowej klawiatury wymaga więcej wysiłku niż z fizycznej. Każdy dodatkowy znak, który trzeba wpisać ręcznie, zwiększa czas wypełniania formularza i ryzyko błędu. Automatyczne wstawianie separatorów zmniejsza liczbę dotknięć o 20–40% dla typowych formatów.

Typy formaterów wprowadzania

Formatery wprowadzania w iOS dzielą się na trzy kategorie: systemowe formatery Foundation, specjalistyczne formatery Apple (PhoneNumberKit) i biblioteki zewnętrzne (InputMask, MaskedTextField). Każda kategoria rozwiązuje swoje zadania i ma cechy implementacji.

Systemowe formatery Foundation

NumberFormatter formatuje wartości liczbowe: sumy pieniężne, procenty, notacje naukowe. Obsługuje lokalizację separatorów grup i znaków dziesiętnych. DateFormatter przekształca daty i czas w zlokalizowane ciągi znaków. Te formatery są przeznaczone do wyświetlania, a nie do maskowania wprowadzania, dlatego trudno zastosować je bezpośrednio do UITextField podczas pisania.

PhoneNumberKit

PhoneNumberKit — biblioteka Apple do formatowania numerów telefonów zgodnie z normami krajowymi. Automatycznie określa kraj na podstawie kodu i stosuje odpowiedni format. Na przykład rosyjski numer +7 912 345-67-89 jest formatowany inaczej niż amerykański +1 212-555-0198. PhoneNumberKit również waliduje numer pod kątem poprawności.

Biblioteki Input Mask

Biblioteki zewnętrzne InputMask zapewniają uniwersalny mechanizm maskowania wprowadzania dla dowolnych formatów: numery kart (0000 0000 0000 0000), daty (DD.MM.RRRR), PESEL (000-000-000 00), NIP (000000000000). Biblioteki działają przez delegata UITextFieldDelegate, przechwytując wprowadzanie i stosując maskę w czasie rzeczywistym.

Abstrakcyjna klasa NSFormatter

NSFormatter — to abstrakcyjna klasa Foundation, od której dziedziczą wszystkie systemowe formatery iOS. Określa ona dwie główne metody: string(for:) do przekształcania obiektu w ciąg znaków i getObjectValue(_:for:errorDescription:) do odwrotnego przekształcania ciągu w obiekt. Ten dwukierunkowy mechanizm pozwala zarówno wyświetlać dane, jak i odczytywać je z pól tekstowych.

Tworzenie własnego formatera na podstawie NSFormatter jest możliwe dla specyficznych formatów nieobjętych klasami systemowymi. W tym celu należy nadpisać metody string(for:) i getObjectValue(_:for:errorDescription:). Własny formater można użyć z UILabel, UITextField i innymi widokami za pomocą właściwości formatter.

Apple zaleca używanie istniejących formaterów Foundation zamiast tworzenia własnych. NumberFormatter poprawnie obsługuje 32 języki i standardy regionalne, DateFormatter uwzględnia kalendarze różnych kultur, a ByteCountFormatter automatycznie przełącza się między bajtami, kilobajtami i megabajtami w zależności od wartości.

NSFormatter obsługuje również lokalizację komunikatów o błędach przy nieprawidłowym wprowadzaniu. Metoda getObjectValue zwraca opis błędu, który można wyświetlić użytkownikowi w zlokalizowanej formie. Jest to szczególnie ważne w formularzach, gdzie użytkownik wprowadza dane w nieprawidłowym formacie — komunikat o błędzie powinien być zrozumiały i w języku interfejsu.

Input Mask i maskowanie wprowadzania

Input Mask (maska wprowadzania) — to wzór, który określa format wprowadzanych danych i automatycznie wstawia separatory podczas pisania. Maska składa się ze znaków zastępczych (zazwyczaj 0 lub 9 dla cyfr, A dla liter) i stałych znaków (nawiasy, myślniki, spacje), które są wstawiane automatycznie. Użytkownik wprowadza tylko znaczące znaki, a separatory są wstawiane przez system.

Najbardziej popularna biblioteka dla iOS — InputMask od RedMadRobot. Obsługuje złożone maski z warunkami, opcjonalnymi blokami i afiksem (prefiks i sufiks). Biblioteka jest zaimplementowana przez delegata, co pozwala używać jej z dowolnym UITextField bez subclassingu. Obsługiwane są maski dla numerów telefonów, kart bankowych, dat, kodów potwierdzających i innych strukturyzowanych danych.

Format maski InputMask używa własnej składni: nawiasy kwadratowe dla obowiązkowych znaków, nawiasy klamrowe dla opcjonalnych, stałe znaki poza nawiasami. Na przykład maska dla numeru karty wygląda jak [0000] [0000] [0000] [0000], a dla daty — [00]{.}[00]{.}[0000]. Opcjonalne bloki w nawiasach klamrowych znikają, jeśli użytkownik nie wprowadzi dla nich danych.

Dla numerów telefonów maska zazwyczaj zawiera kod kraju w afiksie: +7 ([000]) [000]-[00]-[00]. Użytkownik wprowadza tylko 10 cyfr numeru, a znaki +7, (, ), - są wstawiane automatycznie. Podczas usuwania znaku maska poprawnie obsługuje backspace, usuwając ostatni znaczący znak i wracając do poprzedniej pozycji.

Formatowanie numerów telefonów

Formatowanie numerów telefonów — to najczęstszy scenariusz użycia formaterów w aplikacjach mobilnych. iOS zapewnia do tego framework PhoneNumberKit, który automatycznie określa kraj na podstawie kodu i stosuje odpowiedni format krajowy. Biblioteka obsługuje ponad 200 krajów i jest regularnie aktualizowana.

PhoneNumberKit działa w dwóch etapach: określenie formatu i jego zastosowanie. W pierwszym etapie biblioteka analizuje wprowadzony kod kraju (np. +7 określa Rosję) i ładuje reguły formatowania. W drugim etapie stosuje maskę odpowiadającą normie krajowej: dla Rosji to +7 XXX XXX-XX-XX, dla USA — +1 XXX-XXX-XXXX, dla Wielkiej Brytanii — +44 XXXX XXX XXX.

Według Apple Developer Documentation, od iOS 16 pojawił się wbudowany mechanizm formatowania numerów telefonów przez UIContentUnavailableConfiguration. Jednak do pełnego formatowania w czasie rzeczywistym zaleca się używanie PhoneNumberKit przez delegata UITextFieldDelegate. Biblioteka również waliduje numer: sprawdza liczbę cyfr, dopuszczalność kodu kraju i zgodność z formatem krajowym.

Dla aplikacji międzynarodowych ważne jest uwzględnienie, że użytkownik może wprowadzać numer w dowolnym formacie: z +7, 8 (dla Rosji) lub bez kodu kraju. Dobry formater powinien rozpoznawać dowolny początkowy format i normalizować go do jednolitego standardu międzynarodowego z prefiksem + i kodem kraju.

Implementacja formatera w Swift

Implementacja formatera w Swift zależy od wybranego podejścia. Dla systemowych formaterów Foundation używa się właściwości formatter dostępnej od iOS 15 dla UITextField. Dla Input Mask używa się delegata UITextFieldDelegate z biblioteką InputMask. Dla numerów telefonów — PhoneNumberKit przez delegata.

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

Dla NumberFormatter od iOS 15+ dostępna jest właściwość formatter na UITextField, która automatycznie formatuje wprowadzaną liczbę podczas pisania. To podejście nie wymaga implementacji delegata i działa „od razu“ dla formatów pieniężnych, procentów i innych danych liczbowych z uwzględnieniem lokalizacji użytkownika.

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

Dla biblioteki InputMask RedMadRobot konfiguracja odbywa się przez inicjalizację maski i zastosowanie przez delegata. Biblioteka obsługuje wklejanie (paste), usuwanie (backspace) i poprawnie współpracuje z zaznaczeniami tekstu.

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