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), дати (ДД.ММ.РРРР), РНОКПП (000-000-000 00), ІПН (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, (, ), - підставляються автоматично. При видаленні символу маска коректно обробляє backspace, видаляючи останній значущий символ та повертаючись до попередньої позиції.

Форматування номерів телефонів

Форматування номерів телефонів — найчастіший сценарій використання форматувачів у мобільних застосунках. 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 налаштування виконується через ініціалізацію маски та застосування через делегат. Бібліотека підтримує обробку вставки (paste), видалення (backspace) та коректно працює з текстовими виділеннями.

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