Formatter — o que é, formatadores de entrada e NSFormatter

O que é Formatter no iOS?

Formatter no iOS é um componente que converte a entrada bruta do usuário em um formato estruturado de acordo com um padrão definido. Diferentemente da validação simples após o envio do formulário, um formatador funciona em tempo real, corrigindo a exibição dos dados à medida que são inseridos. Esta é a principal diferença: o usuário vê o resultado formatado imediatamente, sem precisar inserir separadores manualmente.

O iOS oferece vários níveis de formatação: formatadores do sistema Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) para exibição de dados, o framework PhoneNumberKit para números de telefone e bibliotecas de terceiros InputMask para máscaras de entrada personalizadas. A escolha do nível depende do tipo de dados e da flexibilidade de formatação necessária.

De acordo com as Apple Human Interface Guidelines, os formatadores de entrada resolvem três tarefas: reduzem a carga cognitiva do usuário (sem necessidade de pensar em separadores), diminuem o número de erros (os dados são inseridos no formato correto) e aceleram o preenchimento de formulários (transição automática entre grupos de dígitos).

Os formatadores são especialmente importantes para dispositivos móveis, onde a entrada com teclado na tela exige mais esforço do que com um físico. Cada caractere extra que precisa ser digitado manualmente aumenta o tempo de preenchimento do formulário e o risco de erro. A inserção automática de separadores reduz o número de toques em 20–40% para formatos típicos.

Tipos de formatadores de entrada

Os formatadores de entrada no iOS se dividem em três categorias: formatadores do sistema Foundation, formatadores especializados da Apple (PhoneNumberKit) e bibliotecas de terceiros (InputMask, MaskedTextField). Cada categoria resolve suas próprias tarefas e tem particularidades de implementação.

Formatadores do sistema Foundation

NumberFormatter formata valores numéricos: quantias monetárias, porcentagens, notações científicas. Suporta a localização de separadores de grupos e decimais. DateFormatter converte datas e horas em strings localizadas. Esses formatadores são projetados para exibição, não para mascaramento de entrada, portanto são difíceis de aplicar diretamente ao UITextField durante a digitação.

PhoneNumberKit

PhoneNumberKit é uma biblioteca da Apple para formatar números de telefone de acordo com os padrões nacionais. Ela detecta automaticamente o país pelo código e aplica o formato correspondente. Por exemplo, um número russo +7 912 345-67-89 é formatado de forma diferente de um americano +1 212-555-0198. O PhoneNumberKit também valida a correção do número.

Bibliotecas Input Mask

As bibliotecas de terceiros InputMask fornecem um mecanismo universal de mascaramento de entrada para qualquer formato: números de cartão (0000 0000 0000 0000), datas (DD.MM.AAAA), SNILS (000-000-000 00), INN (000000000000). As bibliotecas funcionam através do delegado UITextFieldDelegate, interceptando a entrada e aplicando a máscara em tempo real.

Classe abstrata NSFormatter

NSFormatter é uma classe abstrata do Foundation da qual todos os formatadores do sistema iOS herdam. Ela define dois métodos principais: string(for:) para converter um objeto em string e getObjectValue(_:for:errorDescription:) para a conversão inversa de string para objeto. Este mecanismo bidirecional permite tanto exibir dados quanto lê-los de campos de texto.

A criação de um formatador personalizado baseado em NSFormatter é possível para formatos específicos não cobertos pelas classes do sistema. Para isso, é necessário sobrescrever os métodos string(for:) e getObjectValue(_:for:errorDescription:). Um formatador personalizado pode ser usado com UILabel, UITextField e outras views através da propriedade formatter.

A Apple recomenda usar os formatadores existentes do Foundation em vez de criar os próprios. O NumberFormatter lida corretamente com 32 idiomas e padrões regionais, o DateFormatter leva em conta calendários de diferentes culturas, e o ByteCountFormatter alterna automaticamente entre bytes, kilobytes e megabytes dependendo do tamanho do valor.

NSFormatter também suporta a localização de mensagens de erro para entrada incorreta. O método getObjectValue retorna uma descrição do erro que pode ser exibida ao usuário de forma localizada. Isso é especialmente importante para formulários onde o usuário insere dados em formato incorreto — a mensagem de erro deve ser compreensível e no idioma da interface.

Input Mask e mascaramento de entrada

Input Mask (máscara de entrada) é um modelo que define o formato dos dados de entrada e insere automaticamente separadores à medida que são digitados. A máscara consiste em caracteres placeholders (geralmente 0 ou 9 para dígitos, A para letras) e caracteres constantes (parênteses, hífens, espaços) que são inseridos automaticamente. O usuário insere apenas os caracteres significativos, e os separadores são inseridos pelo sistema.

A biblioteca mais popular para iOS é a InputMask da RedMadRobot. Ela suporta máscaras complexas com condições, blocos opcionais e afixos (prefixo e sufixo). A biblioteca é implementada através de um delegado, permitindo seu uso com qualquer UITextField sem subclasses. São suportadas máscaras para números de telefone, cartões bancários, datas, códigos de confirmação e outros dados estruturados.

O formato da máscara InputMask usa sintaxe própria: colchetes para caracteres obrigatórios, chaves para opcionais, caracteres constantes fora dos colchetes. Por exemplo, uma máscara para número de cartão parece [0000] [0000] [0000] [0000], e para data — [00]{.}[00]{.}[0000]. Blocos opcionais entre chaves desaparecem se o usuário não inserir dados para eles.

Para números de telefone, a máscara geralmente inclui o código do país no afixo: +7 ([000]) [000]-[00]-[00]. O usuário insere apenas 10 dígitos do número, enquanto os caracteres +7, (, ), - são inseridos automaticamente. Ao excluir um caractere, a máscara lida corretamente com o backspace, removendo o último caractere significativo e retornando à posição anterior.

Formatação de números de telefone

A formatação de números de telefone é o caso de uso mais comum dos formatadores em aplicativos móveis. O iOS fornece o framework PhoneNumberKit para este propósito, que determina automaticamente o país pelo código e aplica o formato nacional correspondente. A biblioteca suporta mais de 200 países e é atualizada regularmente.

O PhoneNumberKit funciona em duas etapas: detecção do formato e sua aplicação. Na primeira etapa, a biblioteca analisa o código do país inserido (por exemplo, +7 identifica a Rússia) e carrega as regras de formatação. Na segunda etapa, ela aplica uma máscara correspondente ao padrão nacional: para a Rússia é +7 XXX XXX-XX-XX, para os EUA — +1 XXX-XXX-XXXX, para o Reino Unido — +44 XXXX XXX XXX.

De acordo com a Apple Developer Documentation, desde o iOS 16 surgiu um mecanismo integrado de formatação de números de telefone através do UIContentUnavailableConfiguration. No entanto, para formatação completa em tempo real, recomenda-se usar o PhoneNumberKit através do delegado UITextFieldDelegate. A biblioteca também valida o número: verifica a quantidade de dígitos, a validade do código do país e a conformidade com o formato nacional.

Para aplicativos internacionais, é importante considerar que o usuário pode inserir o número em qualquer formato: com +7, 8 (para a Rússia) ou sem código do país. Um bom formatador deve reconhecer qualquer formato inicial e normalizá-lo para um padrão internacional único com prefixo + e código do país.

Implementação do formatador em Swift

A implementação do formatador em Swift depende da abordagem escolhida. Para os formatadores do sistema Foundation, usa-se a propriedade formatter, disponível desde o iOS 15 para UITextField. Para Input Mask, usa-se o delegado UITextFieldDelegate com a biblioteca InputMask. Para números de telefone — PhoneNumberKit através do delegado.

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

Para NumberFormatter com iOS 15+, a propriedade formatter está disponível no UITextField, que formata automaticamente o número inserido à medida que é digitado. Esta abordagem não requer implementação de delegado e funciona imediatamente para formatos de moeda, porcentagens e outros dados numéricos levando em conta a localidade do usuário.

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

Para a biblioteca InputMask da RedMadRobot, a configuração é feita através da inicialização da máscara e aplicação via delegado. A biblioteca suporta manipulação de colagem, exclusão com backspace e funciona corretamente com seleções de texto.

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