Input Mask: o que é, máscaras de entrada e formatação

O que é uma máscara de entrada?

Input Mask (máscara de entrada) é um mecanismo que define um template para os dados inseridos e formata automaticamente o texto à medida que é digitado. O usuário insere apenas caracteres significativos (dígitos, letras), e o sistema adiciona automaticamente separadores: espaços, hifens, parênteses, barras. Esta é a principal diferença do pós-processamento, onde os dados são formatados após a conclusão da entrada.

As máscaras de entrada resolvem três problemas da experiência do usuário. Primeiro — carga cognitiva: o usuário não precisa lembrar o formato dos dados e inserir separadores manualmente. Segundo — velocidade de entrada: a inserção automática de separadores e o avanço para o próximo grupo de caracteres aceleram a digitação. Terceiro — qualidade dos dados: a máscara garante que os dados sejam coletados em um formato uniforme sem variações.

Ao contrário dos formatadores NSFormatter, que funcionam no nível de exibição de dados já inseridos, uma máscara de entrada funciona no nível de entrada: ela controla cada caractere inserido e determina se é permitido na posição atual da máscara. Se um caractere não corresponder à máscara, ele é rejeitado ou ignorado.

De acordo com pesquisas de UX da Apple (2024), as máscaras de entrada são mais eficazes para campos onde o usuário insere dados em um formato desconhecido. Por exemplo, SNILS (000-000-000 00) ou INN (000000000000) — o usuário pode não saber o número exato de dígitos ou a localização dos separadores, e a máscara sugere visualmente o formato correto.

Sintaxe da máscara de entrada

A sintaxe da máscara na biblioteca InputMask usa uma combinação de caracteres placeholder e caracteres constantes. Os placeholders definem o tipo de caractere permitido em cada posição: 0 ou 9 para dígitos, A para letras, _ para qualquer caractere. Os caracteres constantes são separadores inseridos automaticamente: espaços, hifens, parênteses, pontos, barras.

Blocos obrigatórios e opcionais

Colchetes [0] indicam um caractere obrigatório — o usuário deve inserir um dígito nesta posição. Chaves {0} indicam um caractere opcional — se o usuário pular o bloco, a máscara não insere os separadores correspondentes. Por exemplo, a máscara [00]{.}[00]{.}[0000] para uma data: se o usuário não inserir o mês, o separador após o dia também não é exibido.

Afixo da máscara

Caracteres constantes fora de colchetes e chaves são o afixo — eles são sempre exibidos, mesmo que o campo esteja vazio. Por exemplo, na máscara +7 ([000]) [000]-[00]-[00], os caracteres +7, (, ), espaço e hífen são o afixo e não podem ser excluídos pelo usuário. O afixo ajuda o usuário a entender o formato esperado antes mesmo de começar a inserir dados.

Tipos de máscaras por finalidade

As máscaras de entrada são classificadas pelo tipo de dados para os quais são projetadas. Cada tipo tem sua própria estrutura, número de grupos e posicionamento dos separadores. A escolha correta da máscara é crítica para a experiência do usuário — se a máscara não corresponder às expectativas do usuário, ele excluirá os caracteres inseridos automaticamente.

Máscaras para números de telefone

Máscaras de telefone são o tipo mais comum. Um número russo é formatado como +7 ([000]) [000]-[00]-[00], um número americano como +1 ([000]) [000]-[0000]. A máscara deve suportar diferentes quantidades de dígitos no código do país e da cidade. A biblioteca InputMask suporta máscaras de prioridade: se a primeira máscara não for adequada (o usuário inseriu um código de país diferente), a segunda é aplicada.

Máscaras para cartões bancários

Para números de cartão é usada a máscara [0000] [0000] [0000] [0000] com espaços entre grupos de 4 dígitos. Adicionalmente, uma máscara para a data de validade [00]/[00] e código CVV [000] pode ser aplicada. A máscara para número de cartão suporta 16–19 dígitos dependendo do sistema de pagamento: Visa e Mastercard — 16 dígitos, American Express — 15, Maestro — 12–19.

Máscaras para datas e códigos

Máscaras de data usam o formato [00]{.}[00]{.}[0000] com ponto ou barra como separador. Para INN, SNILS e outros identificadores, são usadas máscaras especializadas: INN — [000000000000] (12 dígitos), SNILS — [000]-[000]-[000] [00] (11 dígitos com hifens). Para códigos de verificação — [0000] ou [000000] dependendo do comprimento.

Implementação de máscara em Swift

Implementar uma máscara em Swift é feito configurando um delegate UITextFieldDelegate usando a biblioteca InputMask. A biblioteca fornece a classe MaskedTextFieldDelegate, que se conecta a um campo de texto e formata automaticamente a entrada de acordo com a máscara especificada.

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]"
        )
    }
}

Para números de telefone com detecção automática de país, use máscaras de prioridade. MaskedTextFieldDelegate suporta um array de máscaras: a primeira máscara correspondente é aplicada. Se o usuário inserir o código +1, o formato americano é aplicado; se +7, o formato russo.

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

Para datas com blocos opcionais, use chaves. Se o usuário inserir apenas o dia, a máscara exibe “21”. Se inserir dia e mês — “21.07”. Se inserir todos os três componentes — “21.07.2026”. Blocos opcionais tornam a máscara adaptável e não forçam o usuário a inserir dados que ele não deseja fornecer.

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

Manipulação de colar e excluir

Manipulação correta de colagem é um dos aspectos mais desafiadores da implementação de uma máscara de entrada. Ao colar texto (por exemplo, um número de cartão da área de transferência), a biblioteca deve remover todos os separadores do texto colado, extrair apenas os caracteres significativos e aplicar a máscara aos dados limpos. InputMask da RedMadRobot faz isso automaticamente através do método shouldChangeCharactersIn.

Ao colar texto formatado (com espaços ou hifens), a biblioteca primeiro normaliza os dados: remove todos os caracteres que não correspondem ao padrão da máscara, depois aplica a máscara à string normalizada. Se o texto colado contiver caracteres inválidos (letras em uma máscara de dígitos), eles são ignorados.

A manipulação de exclusão (backspace) em uma máscara requer atenção especial. Ao pressionar backspace, a máscara deve excluir o último caractere significativo, não o separador constante. Se o cursor estiver após um caractere constante, o backspace deve ignorá-lo e excluir o caractere significativo anterior. InputMask implementa esse comportamento através de uma pilha de caracteres inseridos.

Para seleção e substituição de texto, a máscara deve lidar corretamente com situações em que o usuário seleciona parte do texto e o substitui por novo conteúdo. A biblioteca InputMask suporta isso através do método modifyString no MaskedTextFieldDelegate, que aceita um intervalo de substituição e uma nova string.

Melhores práticas para projetar máscaras

O design da máscara começa analisando como o usuário inserirá os dados. Se a maioria dos usuários conhece o formato de cor (número de telefone), a máscara deve ser mínima — apenas separadores entre grupos. Se o formato for desconhecido (SNILS, INN), a máscara deve ser mais informativa, com um afixo e rótulos.

Evite máscaras excessivas com um grande número de caracteres constantes. A máscara +7 ([000]) [000]-[00]-[00] contém 7 caracteres constantes para 10 significativos — isso é aceitável. Mas uma máscara com separadores excessivos que o usuário constantemente contorna causa mais danos do que benefícios. Se você não tem certeza sobre o formato — use entrada livre.

Para aplicativos internacionais, considere que os formatos de dados podem diferir entre países. Um número de telefone nos EUA tem o formato +1 (XXX) XXX-XXXX, enquanto na Itália — +39 XXX XXX XXXX. Use máscaras de prioridade com detecção automática de país por código, ou deixe o usuário escolher um país antes de inserir o número.

De acordo com testes de UX do InputMask, os usuários preferem máscaras que mostram o formato antes do início da entrada (através de placeholder ou afixo) e não bloqueiam a entrada de caracteres. Uma máscara deve ser uma dica, não uma restrição. Se o usuário inserir um caractere que não corresponde à máscara, é melhor permitir do que bloquear a entrada sem explicação.