Formatter — co to je, vstupní formátory a NSFormatter

Co je Formatter v iOS?

Formatter v iOS — to je komponenta, která převádí nezpracovaný uživatelský vstup do strukturovaného formátu podle dané šablony. Na rozdíl od jednoduché validace po odeslání formuláře funguje formátor v reálném čase a upravuje zobrazení dat během jejich zadávání. To je klíčový rozdíl: uživatel vidí naformátovaný výsledek okamžitě, bez nutnosti zadávat oddělovače ručně.

iOS poskytuje několik úrovní formátování: systémové formátory Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) pro zobrazení dat, framework PhoneNumberKit pro telefonní čísla a knihovny třetích stran InputMask pro libovolné vstupní masky. Volba úrovně závisí na typu dat a požadované flexibilitě formátování.

Podle Apple Human Interface Guidelines řeší vstupní formátory tři úkoly: snižují kognitivní zátěž uživatele (nemusí přemýšlet o oddělovačích), snižují počet chyb (data se zadávají ve správném formátu) a zrychlují vyplňování formulářů (automatický přechod mezi skupinami číslic).

Formátory jsou důležité zejména pro mobilní zařízení, kde zadávání přes obrazovkovou klávesnici vyžaduje více úsilí než u fyzické klávesnice. Každý nadbytečný znak, který je třeba zadat ručně, prodlužuje čas vyplnění formuláře a zvyšuje riziko chyby. Automatické dosazování oddělovačů snižuje počet dotyků o 20–40 % u běžných formátů.

Typy vstupních formátorů

Vstupní formátory v iOS se dělí do tří kategorií: systémové formátory Foundation, specializované formátory Apple (PhoneNumberKit) a knihovny třetích stran (InputMask, MaskedTextField). Každá kategorie řeší své úkoly a má své zvláštnosti implementace.

Systémové formátory Foundation

NumberFormatter formátuje číselné hodnoty: peněžní částky, procenta, vědecké notace. Podporuje lokalizaci oddělovačů skupin a desetinných míst. DateFormatter převádí data a časy na lokalizované řetězce. Tyto formátory jsou určeny pro zobrazení, nikoli pro maskování vstupu, proto je obtížné je použít přímo na UITextField při psaní.

PhoneNumberKit

PhoneNumberKit — to je knihovna od Apple pro formátování telefonních čísel podle národních standardů. Automaticky určuje zemi podle kódu a aplikuje odpovídající formát. Například ruské číslo +7 912 345-67-89 se formátuje jinak než americké +1 212-555-0198. PhoneNumberKit také validuje správnost čísla.

Knihovny Input Mask

Knihovny třetích stran InputMask poskytují univerzální mechanismus maskování vstupu pro libovolné formáty: čísla karet (0000 0000 0000 0000), data (DD.MM.RRRR), SNILS (000-000-000 00), INN (000000000000). Knihovny pracují přes delegáta UITextFieldDelegate, zachycují vstup a aplikují masku v reálném čase.

Abstraktní třída NSFormatter

NSFormatter — to je abstraktní třída Foundation, od které dědí všechny systémové formátory iOS. Definuje dvě hlavní metody: string(for:) pro převod objektu na řetězec a getObjectValue(_:for:errorDescription:) pro zpětný převod řetězce na objekt. Tento obousměrný mechanismus umožňuje jak zobrazovat data, tak je číst z textových polí.

Vytvoření vlastního formátoru na základě NSFormatter je možné pro specifické formáty, které nepokrývají systémové třídy. K tomu je třeba přepsat metody string(for:) a getObjectValue(_:for:errorDescription:). Vlastnoručně napsaný formátor lze použít s UILabel, UITextField a dalšími view přes vlastnost formatter.

Apple doporučuje používat stávající formátory Foundation místo vytváření vlastních. NumberFormatter správně zpracovává 32 jazyků a regionálních standardů, DateFormatter zohledňuje kalendáře různých kultur a ByteCountFormatter automaticky přepíná mezi bajty, kilobajty a megabajty podle velikosti hodnoty.

NSFormatter také podporuje lokalizaci chybových zpráv při nesprávném vstupu. Metoda getObjectValue vrací popis chyby, který lze uživateli zobrazit v lokalizované podobě. To je důležité zejména u formulářů, kde uživatel zadává data ve špatném formátu — chybová zpráva musí být srozumitelná a v jazyce rozhraní.

Input Mask a maskování vstupu

Input Mask (vstupní maska) — to je šablona, která určuje formát zadávaných dat a automaticky dosazuje oddělovače při psaní. Maska se skládá ze znaků-zástupců (obvykle 0 nebo 9 pro číslice, A pro písmena) a konstantních znaků (závorky, pomlčky, mezery), které se vkládají automaticky. Uživatel zadává pouze významné znaky, oddělovače dosazuje systém.

Nejoblíbenější knihovna pro iOS — InputMask od RedMadRobot. Podporuje složité masky s podmínkami, volitelnými bloky a afixem (prefix a postfix). Knihovna je implementována přes delegáta, takže ji lze použít s libovolným UITextField bez subclassingu. Podporovány jsou masky pro telefonní čísla, bankovní karty, data, ověřovací kódy a další strukturovaná data.

Formát masky InputMask používá vlastní syntaxi: hranaté závorky pro povinné znaky, složené pro volitelné, konstantní znaky mimo závorky. Například maska pro číslo karty vypadá jako [0000] [0000] [0000] [0000] a pro datum jako [00]{.}[00]{.}[0000]. Volitelné bloky ve složených závorkách zmizí, pokud pro ně uživatel nezadá data.

Pro telefonní čísla maska obvykle zahrnuje kód země v afixu: +7 ([000]) [000]-[00]-[00]. Uživatel zadává pouze 10 číslic čísla a znaky +7, (, ), - se dosazují automaticky. Při mazání znaku maska správně zpracovává backspace, odstraňuje poslední významný znak a vrací se na předchozí pozici.

Formátování telefonních čísel

Formátování telefonních čísel — to je nejčastější scénář použití formátorů v mobilních aplikacích. iOS pro to poskytuje framework PhoneNumberKit, který automaticky určuje zemi podle kódu a aplikuje odpovídající národní formát. Knihovna podporuje více než 200 zemí a pravidelně se aktualizuje.

PhoneNumberKit pracuje ve dvou fázích: určení formátu a jeho aplikace. V první fázi knihovna analyzuje zadaný kód země (např. +7 určuje Rusko) a načítá pravidla formátování. Ve druhé fázi aplikuje masku odpovídající národnímu standardu: pro Rusko to je +7 XXX XXX-XX-XX, pro USA — +1 XXX-XXX-XXXX, pro Velkou Británii — +44 XXXX XXX XXX.

Podle Apple Developer Documentation se od iOS 16 objevil vestavěný mechanismus formátování telefonních čísel přes UIContentUnavailableConfiguration. Pro plnohodnotné formátování v reálném čase se však doporučuje používat PhoneNumberKit přes delegáta UITextFieldDelegate. Knihovna také validuje číslo: kontroluje počet číslic, přípustnost kódu země a soulad s národním formátem.

Pro mezinárodní aplikace je důležité zohlednit, že uživatel může zadat číslo v libovolném formátu: s +7, s 8 (pro Rusko) nebo bez kódu země. Dobrý formátor by měl rozpoznat libovolný počáteční formát a normalizovat jej na jednotný mezinárodní standard s předponou + a kódem země.

Implementace formátoru ve Swiftu

Implementace formátoru ve Swiftu závisí na zvoleném přístupu. Pro systémové formátory Foundation se používá vlastnost formatter, dostupná od iOS 15 pro UITextField. Pro Input Mask se používá delegát UITextFieldDelegate s knihovnou InputMask. Pro telefonní čísla — PhoneNumberKit přes delegáta.

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

Pro NumberFormatter je od iOS 15+ dostupná vlastnost formatter na UITextField, která automaticky formátuje zadávané číslo při psaní. Tento přístup nevyžaduje implementaci delegáta a funguje „z krabice” pro peněžní formáty, procenta a další číselná data s ohledem na lokál uživatele.

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

Pro knihovnu InputMask od RedMadRobot se konfigurace provádí inicializací masky a aplikací přes delegáta. Knihovna podporuje zpracování vložení (paste), mazání (backspace) a správně pracuje s textovými výběry.

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