Input Mask: co to jest, maski wprowadzania i formatowanie

Co to jest Input Mask?

Input Mask (maska wprowadzania) — to mechanizm, który określa wzorzec wprowadzanych danych i automatycznie formatuje tekst podczas jego wpisywania. Użytkownik wprowadza tylko znaczące znaki (cyfry, litery), a system automatycznie dodaje separatory: spacje, myślniki, nawiasy, ukośniki. To kluczowa różnica w stosunku do post-processingu, gdzie dane są formatowane po zakończeniu wprowadzania.

Maski wprowadzania rozwiązują trzy problemy doświadczenia użytkownika. Pierwszy — obciążenie poznawcze: użytkownik nie musi pamiętać formatu danych i ręcznie umieszczać separatorów. Drugi — szybkość wprowadzania: automatyczne wstawianie separatorów i przejście do następnej grupy znaków przyspiesza pisanie. Trzeci — jakość danych: maska gwarantuje, że dane zostaną zebrane w jednolitym formacie bez wariacji.

W przeciwieństwie do formaterów NSFormatter, które działają na poziomie wyświetlania już wprowadzonych danych, Input Mask działa na poziomie wprowadzania: kontroluje każdy wprowadzany znak i określa, czy jest on dozwolony w bieżącej pozycji maski. Jeśli znak nie odpowiada masce, jest odrzucany lub ignorowany.

Według badań UX Apple (2024), maski wprowadzania są najbardziej skuteczne w przypadku pól, w których użytkownik wprowadza dane w nieznanym formacie. Na przykład SNILS (000-000-000 00) lub INN (000000000000) — użytkownik może nie znać dokładnej liczby cyfr ani położenia separatorów, a maska wizualnie podpowiada prawidłowy format.

Składnia maski wprowadzania

Składnia maski w bibliotece InputMask używa kombinacji znaków zastępczych i stałych. Symbole zastępcze określają typ dozwolonego znaku na każdej pozycji: 0 lub 9 dla cyfr, A dla liter, _ dla dowolnego znaku. Znaki stałe — to separatory, które są wstawiane automatycznie: spacje, myślniki, nawiasy, kropki, ukośniki.

Bloki obowiązkowe i opcjonalne

Nawiasy kwadratowe [0] oznaczają obowiązkowy znak — użytkownik musi wprowadzić cyfrę na tej pozycji. Nawiasy klamrowe {0} oznaczają znak opcjonalny — jeśli użytkownik pominie blok, maska nie wstawia odpowiednich separatorów. Na przykład maska [00]{.}[00]{.}[0000] dla daty: jeśli użytkownik nie wprowadzi miesiąca, separator po dniu również nie jest wyświetlany.

Afiks maski

Znaki stałe poza nawiasami kwadratowymi i klamrowymi stanowią afiks — są wyświetlane zawsze, nawet jeśli pole jest puste. Na przykład w masce +7 ([000]) [000]-[00]-[00] znaki +7, (, ), spacja i myślnik są afiksem i nie mogą być usunięte przez użytkownika. Afiks pomaga użytkownikowi zrozumieć oczekiwany format jeszcze przed rozpoczęciem wprowadzania.

Typy masek według przeznaczenia

Maski wprowadzania są klasyfikowane według typu danych, dla których są przeznaczone. Każdy typ ma swoją strukturę, liczbę grup i rozmieszczenie separatorów. Prawidłowy wybór maski ma kluczowe znaczenie dla doświadczenia użytkownika — jeśli maska nie odpowiada oczekiwaniom użytkownika, będzie on usuwał automatycznie wstawione znaki.

Maski dla numerów telefonów

Maski telefoniczne — najbardziej rozpowszechniony typ. Rosyjski numer jest formatowany jako +7 ([000]) [000]-[00]-[00], amerykański jako +1 ([000]) [000]-[0000]. Maska musi obsługiwać różną liczbę cyfr w kodzie kraju i mieście. Biblioteka InputMask obsługuje maski priorytetowe: jeśli pierwsza maska nie pasuje (użytkownik wprowadził kod innego kraju), stosowana jest druga.

Maski dla kart bankowych

Dla numerów kart używana jest maska [0000] [0000] [0000] [0000] ze spacjami między grupami po 4 cyfry. Dodatkowo może być stosowana maska dla daty ważności [00]/[00] i kodu CVV [000]. Maska dla numeru karty obsługuje 16–19 cyfr w zależności od systemu płatności: Visa i Mastercard — 16 cyfr, American Express — 15, Maestro — 12–19.

Maski dla dat i kodów

Maski dat używają formatu [00]{.}[00]{.}[0000] z separatorem w postaci kropki lub ukośnika. Dla INN, SNILS i innych identyfikatorów stosowane są specjalistyczne maski: INN — [000000000000] (12 cyfr), SNILS — [000]-[000]-[000] [00] (11 cyfr z myślnikami). Dla kodów weryfikacyjnych — [0000] lub [000000] w zależności od długości.

Implementacja maski w Swift

Implementacja maski w Swift odbywa się przez ustawienie delegata UITextFieldDelegate z użyciem biblioteki InputMask. Biblioteka udostępnia klasę MaskedTextFieldDelegate, która podłącza się do pola tekstowego i automatycznie formatuje wprowadzanie zgodnie z zadaną maską.

import InputMask

class PaymentViewController: UIViewController {

    @IBOutlet var cardField: UITextField!
    @IBOutlet var dateField: UITextField!
    @IBOutlet var cvvField: UITextField!

    var cardListener: MaskedTextFieldDelegate!

    override func viewDidLoad() {
        super.viewDidLoad()
        cardListener = MaskedTextFieldDelegate()
        cardListener.primaryMaskFormat = "[0000] [0000] [0000] [0000]"
        cardField.delegate = cardListener
        dateField.delegate = MaskedTextFieldDelegate(
            primaryMaskFormat: "[00]/[00]"
        )
        cvvField.delegate = MaskedTextFieldDelegate(
            primaryMaskFormat: "[000]"
        )
    }
}

Dla numerów telefonów z automatycznym określaniem kraju używaj masek priorytetowych. MaskedTextFieldDelegate obsługuje tablicę masek: pierwsza pasująca jest stosowana. Jeśli użytkownik wprowadzi kod +1, stosowany jest format amerykański, jeśli +7 — rosyjski.

let phoneListener = MaskedTextFieldDelegate()
phoneListener.primaryMaskFormat = "+7 ([000]) [000]-[00]-[00]"
phoneListener.affinityMask = [
    "+1 ([000]) [000]-[0000]",
    "+44 [000] [000] [0000]",
    "+49 [000] [0000] [0000]"
]

Dla daty z blokami opcjonalnymi używaj nawiasów klamrowych. Jeśli użytkownik wprowadzi tylko dzień, maska wyświetla się jako „21". Jeśli wprowadzi dzień i miesiąc — „21.07". Jeśli wszystkie trzy składniki — „21.07.2026". Bloki opcjonalne sprawiają, że maska jest adaptacyjna i nie zmusza użytkownika do wprowadzania danych, których nie chce podać.

let dateListener = MaskedTextFieldDelegate(
    primaryMaskFormat: "[00]{.}[00]{.}[0000]"
)
dateField.delegate = dateListener

Obsługa wklejania i usuwania

Prawidłowa obsługa wklejania — jeden z najtrudniejszych aspektów implementacji maski wprowadzania. Podczas wklejania tekstu (na przykład numeru karty ze schowka) biblioteka musi usunąć wszystkie separatory z wklejanego tekstu, wyodrębnić tylko znaczące znaki i zastosować maskę do czystych danych. InputMask od RedMadRobot robi to automatycznie przez metodę shouldChangeCharactersIn.

Podczas wklejania sformatowanego tekstu (ze spacjami lub myślnikami) biblioteka najpierw normalizuje dane: usuwa wszystkie znaki niepasujące do wzorca maski, a następnie stosuje maskę do znormalizowanego ciągu. Jeśli wklejony tekst zawiera niedozwolone znaki (litery w masce cyfrowej), są one ignorowane.

Obsługa usuwania (backspace) w masce wymaga szczególnej uwagi. Po naciśnięciu backspace maska musi usunąć ostatni znaczący znak, a nie stały separator. Jeśli kursor znajduje się za stałym znakiem, backspace powinien go pominąć i usunąć poprzedni znaczący znak. InputMask implementuje to zachowanie przez stos wprowadzonych znaków.

Dla zaznaczania i zastępowania tekstu maska musi poprawnie obsługiwać sytuacje, gdy użytkownik zaznacza część tekstu i zastępuje go nowym. Biblioteka InputMask obsługuje to przez metodę modifyString w MaskedTextFieldDelegate, która przyjmuje zakres zastąpienia i nowy ciąg.

Zalecenia dotyczące projektowania masek

Projektowanie maski rozpoczyna się od analizy tego, jak użytkownik będzie wprowadzać dane. Jeśli większość użytkowników zna format na pamięć (numer telefonu), maska powinna być minimalna — tylko separatory między grupami. Jeśli format jest nieznany (SNILS, INN), maska powinna być bardziej informacyjna, z afiksem i podpisami.

Unikaj nadmiarowych masek z dużą liczbą stałych znaków. Maska +7 ([000]) [000]-[00]-[00] zawiera 7 stałych znaków na 10 znaczących — to akceptowalne. Ale maska z nadmiarowymi separatorami, którą użytkownik stale omija, przynosi więcej szkody niż pożytku. Jeśli masz wątpliwości co do formatu — użyj swobodnego wprowadzania.

Dla aplikacji międzynarodowych uwzględnij, że format danych może się różnić w różnych krajach. Numer telefonu w USA ma format +1 (XXX) XXX-XXXX, a we Włoszech — +39 XXX XXX XXXX. Używaj masek priorytetowych z automatycznym określaniem kraju według kodu lub zapewnij użytkownikowi wybór kraju przed wprowadzeniem numeru.

Według badań UX InputMask, użytkownicy preferują maski, które pokazują format przed rozpoczęciem wprowadzania (przez placeholder lub afiks) i nie blokują wprowadzania znaków. Maska powinna być podpowiedzią, a nie ograniczeniem. Jeśli użytkownik wprowadza znak niepasujący do maski, lepiej pozwolić mu to zrobić, niż zablokować wprowadzanie bez wyjaśnienia przyczyny.