Keyboard Avoidance — essência, métodos de implementação e deslocamento de interface

O que é Keyboard Avoidance

Keyboard Avoidance é um conjunto de técnicas que garantem a visibilidade do campo de entrada ativo quando o teclado do sistema aparece no iOS. O problema básico: o teclado ocupa até 50% da tela e cobre a metade inferior da interface, incluindo campos de texto, botões de envio e outros elementos.

Existem três abordagens principais para implementação: gerenciamento manual através de Keyboard Notifications (método clássico, funciona desde o iOS 3.0), uso de UIScrollView com rolagem automática (recomendado pela Apple) e Keyboard Layout Guide (método moderno com iOS 15+). A escolha depende da versão mínima suportada do iOS e da complexidade da interface.

Segundo a Apple, a falta de Keyboard Avoidance é uma das causas mais comuns de rejeição de aplicativos durante a revisão se os campos de texto estiverem completamente cobertos pelo teclado. As App Store Guidelines exigem explicitamente que todos os elementos interativos permaneçam acessíveis durante a entrada ativa.

Por que o iOS não faz isso automaticamente

O iOS não pode determinar automaticamente qual elemento deve permanecer visível porque não conhece a semântica da interface. Em um formulário simples com um campo de texto, basta mover a tela inteira para cima. Em uma interface complexa com painéis personalizados, botões flutuantes e múltiplas seções, é necessária uma lógica de comportamento diferente.

Além disso, alguns aplicativos intencionalmente não deslocam o conteúdo — por exemplo, calculadoras de teclado ou editores onde o teclado faz parte da área de trabalho. O iOS deixa a decisão para o desenvolvedor, fornecendo APIs flexíveis para qualquer cenário.

Notificações de Frame do Teclado

UIKeyboardWillShowNotification é a notificação principal que o iOS envia antes do teclado aparecer. Ela contém um CGRect com a posição final do teclado no dicionário UIResponder.keyboardFrameEndUserInfoKey, bem como a duração da animação em UIResponder.keyboardAnimationDurationUserInfoKey.

O manipulador da notificação deve calcular a sobreposição entre o campo de texto ativo e o teclado, depois alterar a margem inferior (contentInset ou frame) do contêiner. Se o campo estiver abaixo da borda superior do teclado, o conteúdo desloca para cima na quantidade da sobreposição. Quando o teclado é ocultado, a margem retorna ao seu valor original.

@objc func keyboardWillShow(_ notification: Notification) {
    guard let keyboardFrame = notification
        .userInfo?[UIResponder.keyboardFrameEndUserInfoKey]
        as? CGRect else { return }
    
    let keyboardHeight = keyboardFrame.height
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
}

Ao usar notificações, é importante lidar com a animação de forma síncrona com o teclado do sistema. O iOS fornece a curva de animação (UIResponder.keyboardAnimationCurveUserInfoKey) e a duração. Use UIView.animate com esses parâmetros para que o conteúdo se desloque suavemente, simultaneamente ao aparecimento do teclado.

Keyboard Layout Guide no iOS 15+

UIScrollView.keyboardLayoutGuide é uma API moderna para Keyboard Avoidance, introduzida no iOS 15. Ela rastreia automaticamente a posição do teclado e atualiza as restrições do Auto Layout que conectam a parte inferior da interface à borda superior do teclado.

Para usá-la, basta ativar o layout guide em um UIScrollView ou UIStackView e anexar a restrição inferior do conteúdo a ele. Nenhum trabalho manual com notificações, cálculo de altura ou animação é necessário — o sistema faz tudo automaticamente, sincronizando a animação com o aparecimento e ocultação do teclado.

// Habilitar Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// Fixar restrição inferior ao topo do teclado
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard é uma propriedade que determina se o guia deve responder a um teclado que pode ser destacado da borda inferior (no iPad). Defina como true apenas se a interface funcionar corretamente com um teclado flutuante. Para iPhone, esta propriedade é ignorada — o teclado está sempre preso à borda inferior.

UIScrollView e o teclado

UIScrollView é um contêiner que a Apple recomenda usar como base para Keyboard Avoidance. Quando o teclado aparece, a scroll view aumenta seu contentInset.bottom, permitindo rolar o conteúdo para cima e tornar o campo ativo visível.

O método chave é scrollRectToVisible, que rola programaticamente a scroll view para que o retângulo especificado (o campo de texto ativo) fique na área visível. Combinar a alteração do contentInset com uma chamada scrollRectToVisible garante que o campo não só fique descoberto, mas também posicionado na parte superior da área visível.

func adjustScrollForKeyboard(
    keyboardHeight: CGFloat,
    activeField: UIView
) {
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
    
    var visibleRect = view.frame
    visibleRect.size.height -= keyboardHeight
    
    if activeField.frame.origin.y > visibleRect.maxY {
        scrollView.scrollRectToVisible(
            activeField.frame, animated: true
        )
    }
}

Para UIViewController com UITableView, a Apple recomenda usar UITableViewController, que ajusta automaticamente o contentInset quando o teclado aparece. Se você usar UIViewController com uma tabela adicionada, precisará implementar o Keyboard Avoidance manualmente — o UITableViewController não fornece esse comportamento para controladores personalizados.

Auto Layout e Keyboard Avoidance

Auto Layout permite implementar Keyboard Avoidance sem programar animações — basta alterar a atividade (isActive) de uma restrição específica ou atualizar sua constante em resposta a uma notificação do teclado.

Um esquema típico: criar um IBOutlet NSLayoutConstraint para a margem inferior da scroll view ou conteúdo, e no manipulador keyboardWillShow definir constraint.constant = keyboardHeight, e no keyboardWillHide redefinir para 0. Atualize o layout via layoutIfNeeded dentro de um bloco animate para uma transição suave.

Ao usar UIStackView, alterar as restrições da margem inferior também funciona: a stack view redistribui os elementos filhos automaticamente. No entanto, se a stack view estiver dentro de um UIScrollView, é preferível gerenciar o contentInset da própria scroll view, em vez das restrições dentro dela.

Soluções de terceiros para Keyboard Avoidance

IQKeyboardManager é a biblioteca mais popular (mais de 16.000 estrelas no GitHub) que implementa Keyboard Avoidance automático sem uma única linha de código no controlador. Ela usa method swizzling para rastrear campos de texto e eleva automaticamente o conteúdo quando o teclado aparece.

A biblioteca oferece configurações flexíveis: você pode especificar a distância entre o campo e o teclado, ativar/desativar para controladores específicos e configurar o comportamento para UITextView e visualizações de entrada personalizadas. No entanto, o method swizzling pode entrar em conflito com outras bibliotecas, e a Apple não recomenda essa abordagem para código de produção devido a efeitos colaterais imprevisíveis.

As alternativas incluem TPKeyboardAvoiding (uma biblioteca leve, ~2.000 estrelas) e KeyboardManager da comunidade. Para projetos modernos, a Apple recomenda usar as ferramentas integradas do iOS 15+, e para projetos com uma versão mínima mais baixa — UIScrollView com contentInset, que é a solução integrada mais confiável.