Formatter — qué es, formateadores de entrada y NSFormatter

¿Qué es Formatter en iOS?

Formatter en iOS es un componente que convierte la entrada del usuario sin procesar en un formato estructurado según una plantilla dada. A diferencia de la validación simple después del envío del formulario, un formateador funciona en tiempo real, corrigiendo la visualización de los datos a medida que se ingresan. Esta es una diferencia clave: el usuario ve el resultado formateado inmediatamente, sin necesidad de ingresar separadores manualmente.

iOS proporciona varios niveles de formateo: formateadores del sistema Foundation (NumberFormatter, DateFormatter, ByteCountFormatter) para mostrar datos, el framework PhoneNumberKit para números de teléfono y bibliotecas de terceros InputMask para máscaras de entrada personalizadas. La elección del nivel depende del tipo de datos y la flexibilidad de formateo requerida.

Según las Apple Human Interface Guidelines, los formateadores de entrada resuelven tres tareas: reducen la carga cognitiva del usuario (no es necesario pensar en separadores), disminuyen la cantidad de errores (los datos se ingresan en el formato correcto) y aceleran el llenado de formularios (transición automática entre grupos de dígitos).

Los formateadores son especialmente importantes para dispositivos móviles, donde la entrada con teclado en pantalla requiere más esfuerzo que con uno físico. Cada carácter adicional que debe ingresarse manualmente aumenta el tiempo de llenado del formulario y el riesgo de error. La inserción automática de separadores reduce la cantidad de toques en un 20–40% para formatos típicos.

Tipos de formateadores de entrada

Los formateadores de entrada en iOS se dividen en tres categorías: formateadores del sistema Foundation, formateadores especializados de Apple (PhoneNumberKit) y bibliotecas de terceros (InputMask, MaskedTextField). Cada categoría resuelve sus propias tareas y tiene particularidades de implementación.

Formateadores del sistema Foundation

NumberFormatter formatea valores numéricos: cantidades monetarias, porcentajes, notaciones científicas. Soporta la localización de separadores de grupos y decimales. DateFormatter convierte fechas y horas en cadenas localizadas. Estos formateadores están diseñados para visualización, no para enmascaramiento de entrada, por lo que son difíciles de aplicar directamente a UITextField durante la escritura.

PhoneNumberKit

PhoneNumberKit es una biblioteca de Apple para formatear números de teléfono según los estándares nacionales. Detecta automáticamente el país por código y aplica el formato correspondiente. Por ejemplo, un número ruso +7 912 345-67-89 se formatea de manera diferente a uno estadounidense +1 212-555-0198. PhoneNumberKit también valida la corrección del número.

Bibliotecas Input Mask

Las bibliotecas de terceros InputMask proporcionan un mecanismo universal de enmascaramiento de entrada para cualquier formato: números de tarjeta (0000 0000 0000 0000), fechas (DD.MM.AAAA), SNILS (000-000-000 00), INN (000000000000). Las bibliotecas funcionan a través del delegado UITextFieldDelegate, interceptando la entrada y aplicando la máscara en tiempo real.

Clase abstracta NSFormatter

NSFormatter es una clase abstracta de Foundation de la que heredan todos los formateadores del sistema iOS. Define dos métodos principales: string(for:) para convertir un objeto en cadena y getObjectValue(_:for:errorDescription:) para la conversión inversa de cadena a objeto. Este mecanismo bidireccional permite tanto mostrar datos como leerlos desde campos de texto.

La creación de un formateador personalizado basado en NSFormatter es posible para formatos específicos no cubiertos por las clases del sistema. Para ello, es necesario sobrescribir los métodos string(for:) y getObjectValue(_:for:errorDescription:). Un formateador personalizado se puede usar con UILabel, UITextField y otras vistas a través de la propiedad formatter.

Apple recomienda usar los formateadores existentes de Foundation en lugar de crear los propios. NumberFormatter maneja correctamente 32 idiomas y estándares regionales, DateFormatter tiene en cuenta los calendarios de diferentes culturas, y ByteCountFormatter cambia automáticamente entre bytes, kilobytes y megabytes según el tamaño del valor.

NSFormatter también soporta la localización de mensajes de error para entrada incorrecta. El método getObjectValue devuelve una descripción del error que se puede mostrar al usuario en forma localizada. Esto es especialmente importante para formularios donde el usuario ingresa datos en un formato incorrecto — el mensaje de error debe ser comprensible y estar en el idioma de la interfaz.

Input Mask y enmascaramiento de entrada

Input Mask (máscara de entrada) es una plantilla que define el formato de los datos de entrada e inserta automáticamente separadores a medida que se escribe. La máscara consta de caracteres de marcador de posición (generalmente 0 o 9 para dígitos, A para letras) y caracteres constantes (paréntesis, guiones, espacios) que se insertan automáticamente. El usuario ingresa solo los caracteres significativos, y los separadores los inserta el sistema.

La biblioteca más popular para iOS es InputMask de RedMadRobot. Soporta máscaras complejas con condiciones, bloques opcionales y afijos (prefijo y sufijo). La biblioteca se implementa a través de un delegado, lo que permite usarla con cualquier UITextField sin subclasificación. Se soportan máscaras para números de teléfono, tarjetas bancarias, fechas, códigos de confirmación y otros datos estructurados.

El formato de máscara InputMask utiliza su propia sintaxis: corchetes para caracteres obligatorios, llaves para opcionales, caracteres constantes fuera de los corchetes. Por ejemplo, una máscara para número de tarjeta se ve como [0000] [0000] [0000] [0000], y para fecha — [00]{.}[00]{.}[0000]. Los bloques opcionales entre llaves desaparecen si el usuario no ingresa datos para ellos.

Para números de teléfono, la máscara generalmente incluye el código de país en el afijo: +7 ([000]) [000]-[00]-[00]. El usuario ingresa solo 10 dígitos del número, mientras que los caracteres +7, (, ), - se insertan automáticamente. Al eliminar un carácter, la máscara maneja correctamente la tecla de retroceso, eliminando el último carácter significativo y volviendo a la posición anterior.

Formateo de números de teléfono

El formateo de números de teléfono es el caso de uso más frecuente de los formateadores en aplicaciones móviles. iOS proporciona el framework PhoneNumberKit para este propósito, que determina automáticamente el país por código y aplica el formato nacional correspondiente. La biblioteca soporta más de 200 países y se actualiza regularmente.

PhoneNumberKit funciona en dos etapas: detección del formato y su aplicación. En la primera etapa, la biblioteca analiza el código de país ingresado (por ejemplo, +7 identifica Rusia) y carga las reglas de formateo. En la segunda etapa, aplica una máscara correspondiente al estándar nacional: para Rusia es +7 XXX XXX-XX-XX, para EE. UU. — +1 XXX-XXX-XXXX, para el Reino Unido — +44 XXXX XXX XXX.

Según la Apple Developer Documentation, desde iOS 16 ha aparecido un mecanismo integrado de formateo de números de teléfono a través de UIContentUnavailableConfiguration. Sin embargo, para un formateo completo en tiempo real, se recomienda usar PhoneNumberKit a través del delegado UITextFieldDelegate. La biblioteca también valida el número: verifica la cantidad de dígitos, la validez del código de país y el cumplimiento del formato nacional.

Para aplicaciones internacionales, es importante tener en cuenta que el usuario puede ingresar el número en cualquier formato: con +7, 8 (para Rusia) o sin código de país. Un buen formateador debe reconocer cualquier formato inicial y normalizarlo a un estándar internacional único con prefijo + y código de país.

Implementación del formateador en Swift

La implementación del formateador en Swift depende del enfoque elegido. Para los formateadores del sistema Foundation, se utiliza la propiedad formatter, disponible desde iOS 15 para UITextField. Para Input Mask, se utiliza el delegado UITextFieldDelegate con la biblioteca InputMask. Para números de teléfono — PhoneNumberKit a través del 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 con iOS 15+, está disponible la propiedad formatter en UITextField, que formatea automáticamente el número ingresado a medida que se escribe. Este enfoque no requiere implementar un delegado y funciona de fábrica para formatos de moneda, porcentajes y otros datos numéricos teniendo en cuenta la configuración regional del usuario.

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

Para la biblioteca InputMask de RedMadRobot, la configuración se realiza mediante la inicialización de la máscara y su aplicación a través de un delegado. La biblioteca soporta el manejo de pegado, eliminación con retroceso y funciona correctamente con selecciones 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
    }
}