UITextField — o que é, configuração do campo de entrada e princípio de funcionamento

O que é UITextField

UITextField é uma classe do framework UIKit projetada para entrada de texto de uma única linha pelo usuário. A classe herda de UIControl, permitindo a inscrição em eventos de entrada por meio do mecanismo target-action: addTarget(self, action: Selector("textChanged:"), for: editingChanged). UITextField exibe uma borda (borderStyle), texto placeholder quando o campo está vazio, um botão de limpeza (clearButtonMode) e pode conter visualizações auxiliares esquerda/direita. O campo mostra/oculta automaticamente o teclado ao ganhar/perder foco por meio de becomeFirstResponder e resignFirstResponder. O tamanho do campo é determinado por intrinsicContentSize com base na fonte e no estilo da borda. Para criar um UITextField no Interface Builder (Storyboard/XIB), use a Object Library; programaticamente, use o inicializador UITextField(frame: CGRect). A classe é totalmente compatível com a arquitetura moderna do iOS: Combine publishers, @Published no SwiftUI por meio de UIViewRepresentable e Diffable Data Source para formulários.

Tipos de teclado UIKeyboardType

UITextField suporta 12 tipos de teclado por meio da propriedade keyboardType. Cada tipo otimiza o conjunto de caracteres para um cenário de entrada específico. UIKeyboardType.default — teclado QWERTY padrão. UIKeyboardType.numberPad — apenas dígitos sem símbolos adicionais (ideal para códigos PIN e números de telefone). UIKeyboardType.emailAddress — teclado com @ e ponto na camada principal. UIKeyboardType.URL — teclado com .com, / e ponto na camada principal. UIKeyboardType.phonePad — teclado numérico com +, *, # para inserir números de telefone. UIKeyboardType.decimalPad — dígitos com ponto decimal para inserir preços. UIKeyboardType.webSearch — teclado com botão Ir otimizado para consultas de pesquisa. UIKeyboardType.asciiCapable — apenas caracteres ASCII para texto latino. O teclado aparece ao chamar becomeFirstResponder e esconde ao chamar resignFirstResponder. O tipo de teclado pode ser alterado dinamicamente durante a edição.

Delegado UITextFieldDelegate e seus métodos

UITextFieldDelegate é um protocolo que define o comportamento do campo de texto em diferentes estágios da entrada. Métodos principais: textFieldShouldBeginEditing(textField) — retorna um Bool permitindo ou negando o início da edição; textFieldDidBeginEditing — chamado após o teclado aparecer; textFieldShouldEndEditing — verifica se a edição pode ser concluída (se false, o campo não perde o foco); textFieldDidEndEditing — chamado após o teclado esconder; textFieldShouldChangeCharactersInRange — chamado a cada entrada de caractere, permite filtrar a entrada (apenas um caractere é permitido, se false for retornado — o caractere não é adicionado); textFieldShouldReturn — chamado ao pressionar Return/Go/Next/Search, usado para ir ao próximo campo. O delegado não é Optional: todos os métodos têm uma implementação padrão, mas para comportamento personalizado você precisa sobrescrever o método correspondente.

Gerenciamento de foco por meio de shouldReturn

O método shouldReturn é o padrão para navegar entre campos de formulário. Implementação: textFieldShouldReturn(textField) — verifique qual textField acionou o evento e mova o foco para o próximo campo por meio de becomeFirstResponder(). Se for o último campo, chame resignFirstResponder() para esconder o teclado. Use IBOutlet collection ou IBOutlets separados para cada campo para armazenar referências aos campos.

Secure Text Entry e visualizações left/right personalizadas

isSecureTextEntry — uma propriedade UITextField que, quando true, substitui os caracteres inseridos por bolinhas (•) e bloqueia a cópia de texto por meio de UIMenuController. Usado para campos de senha, códigos PIN, CVV. Ao alternar entre o modo seguro e texto simples (show/hide password), defina textField.isSecureTextEntry.toggle(). Importante: ao alterar isSecureTextEntry, o texto do campo é redefinido — salve-o com antecedência. LeftView e RightView são UIViews personalizados exibidos dentro do campo de entrada à esquerda ou direita. Uso típico: um ícone de pesquisa em leftView, um botão "Limpar" em rightView. Configuração: textField.leftViewMode = always (sempre) ou whileEditing (apenas durante a edição). As visualizações left/right são posicionadas automaticamente dentro do campo de texto considerando o preenchimento. O tamanho da visualização é definido por meio de bounds ou Auto Layout.

import UIKit

class LoginViewController: UIViewController {
    let passwordField = UITextField()

    override func viewDidLoad() {
        super.viewDidLoad()
        passwordField.isSecureTextEntry = true
        passwordField.placeholder = "Password"
        passwordField.keyboardType = .asciiCapable
        passwordField.delegate = self

        // Botão personalizado mostrar/ocultar senha
        let showButton = UIButton(type: .system)
        showButton.setTitle("Mostrar", for: .normal)
        showButton.addTarget(self, action: #selector(togglePasswordVisibility),
                       for: .touchUpInside)
        passwordField.rightView = showButton
        passwordField.rightViewMode = .always
    }

    @objc func togglePasswordVisibility() {
        passwordField.isSecureTextEntry.toggle()
    }
}

Configuração de UITextInputTraits

UITextInputTraits é um protocolo que define a aparência visual e comportamental do teclado para UITextField. Propriedades principais: autocorrectionType (.default, .no, .yes) — ativa ou desativa a autocorreção de texto; autocapitalizationType (.none, .words, .sentences, .allCharacters) — Caps Lock automático para o primeiro caractere; spellCheckingType — verificação ortográfica; returnKeyType (.done, .go, .next, .search, .send, .continue, .join, .route, .emergencyCall) — texto do botão Return no teclado; enablesReturnKeyAutomatically — bloqueio automático do botão Return quando o campo está vazio. Para campos de entrada de nome, use autocapitalizationType = .words; para email, use autocorrectionType = .no; para URL, use keyboardType = .URL + autocapitalizationType = .none. As traits são configuradas após a inicialização do campo antes de sua exibição. Alterar traits dinamicamente atualiza o teclado em sua próxima aparição.

Return Key Type e navegação por formulário

Return Key Type define o texto do botão no teclado: Next — ir para o próximo campo, Done — concluir entrada, Search — iniciar pesquisa, Send — enviar o formulário, Continue — continuar preenchendo. Em combinação com o método delegado shouldReturn, o returnKeyType permite uma UX natural: o usuário preenche os campos, pressionando Next para ir ao próximo, e Done para enviar no último campo. Para personalização do texto do botão, use UIButtonConfiguration no iOS 15+.

Placeholder, formatação e máscara de entrada

O placeholder do UITextField é o texto exibido em cinza quando o campo está vazio. Configuração: textField.placeholder = "Enter email". Para personalizar a cor e a fonte do placeholder, use attributedPlaceholder com NSAttributedString. A máscara de entrada é implementada por meio do método delegado shouldChangeCharactersInRange — suporta formatos de número de telefone, data, cartão de crédito e SNILS. A máscara de entrada permite separar a exibição do valor: o usuário vê texto formatado (por exemplo, +7 (999) 999-99-99), enquanto o modelo armazena "79999999999". Exemplo de implementação: armazene a máscara como uma string com caracteres X para substituição; a cada entrada, forme a string formatada e retorne false em shouldChangeCharactersInRange, substituindo o texto do campo por meio de textField.text = formattedText. Para números, use NumberFormatter e o keyboardType decimal.

extension LoginViewController: UITextFieldDelegate {
    func textFieldShouldReturn(
        textField: UITextField
    ) -> Bool {
        if textField == emailField {
            passwordField.becomeFirstResponder()
        } else if textField == passwordField {
            textField.resignFirstResponder()
            loginTapped()
        }
        return true
    }

    func textField(
        textField: UITextField,
        shouldChangeCharactersIn range: NSRange,
        replacementString string: String
    ) -> Bool {
        // Bloquear espaços no email
        if textField == emailField && string == " " {
            return false
        }
        // Limite de comprimento da senha
        if textField == passwordField {
            let newLength = (textField.text?.count ?? 0) +
                string.count - range.length
            return newLength <= 32
        }
        return true
    }
}

Exemplos de código: validação e formulário

Vamos ver um exemplo completo de implementação de um formulário de login com UITextField, validação de email e feedback visual. O formulário contém dois campos: emailField (teclado emailAddress, sem autocorreção) e passwordField (secureTextEntry). A validação é realizada em shouldChangeCharactersInRange e adicionalmente ao pressionar o botão Login. Para feedback visual: borda vermelha (layer.borderColor) em erro, verde — em validação bem-sucedida. Redefinição da borda ao iniciar a edição em textFieldDidBeginEditing.

Validação de email com expressão regular

A validação de email é realizada por meio de NSPredicate com o formato "SELF MATCHES %@" e uma expressão regular para verificação básica de formato. A verificação real de existência do email deve ser feita no servidor. Para validação avançada, use a biblioteca SwiftValidators ou Combine publishers. Exemplo: NSPredicate(format: "SELF MATCHES [c] %@", emailRegex).evaluate(with: email). A borda do campo é atualizada por meio de um bloco de animação para uma transição suave.

func validateEmail(textField: UITextField) {
    guard let text = textField.text, !text.isEmpty else {
        textField.layer.borderColor = UIColor.clear.cgColor
        return
    }

    let emailRegex = "[A-Z0-9a-z._%+-]+@[A-Za-z0-9.-]+\\.\\p{L}{2,}"
    let predicate = NSPredicate(format: "SELF MATCHES [c] %@", emailRegex)
    let isValid = predicate.evaluate(with: text)

    UIView.animate(withDuration: 0.2) {
        textField.layer.borderColor = isValid
            ? UIColor.systemGreen.cgColor
            : UIColor.systemRed.cgColor
        textField.layer.borderWidth = 1.0
        textField.layer.cornerRadius = 6.0
    }
}