Keyboard Avoidance — esencia, métodos de implementación y desplazamiento de interfaz

Qué es Keyboard Avoidance

Keyboard Avoidance es un conjunto de técnicas que garantizan la visibilidad del campo de entrada activo cuando aparece el teclado del sistema en iOS. El problema básico: el teclado ocupa hasta el 50% de la pantalla y cubre la mitad inferior de la interfaz, incluidos campos de texto, botones de envío y otros elementos.

Existen tres enfoques principales para la implementación: gestión manual mediante Keyboard Notifications (método clásico, funciona desde iOS 3.0), uso de UIScrollView con desplazamiento automático (recomendado por Apple) y Keyboard Layout Guide (método moderno con iOS 15+). La elección depende de la versión mínima compatible de iOS y la complejidad de la interfaz.

Según Apple, la falta de Keyboard Avoidance es una de las causas más frecuentes de rechazo de aplicaciones durante la revisión si los campos de texto quedan completamente cubiertos por el teclado. Las App Store Guidelines exigen explícitamente que todos los elementos interactivos sigan siendo accesibles durante la entrada activa.

Por qué iOS no lo hace automáticamente

iOS no puede determinar automáticamente qué elemento debe permanecer visible porque desconoce la semántica de la interfaz. En un formulario simple con un campo de texto, basta con mover toda la pantalla hacia arriba. En una interfaz compleja con paneles personalizados, botones flotantes y múltiples secciones, se requiere una lógica de comportamiento diferente.

Además, algunas aplicaciones no desplazan el contenido intencionadamente — por ejemplo, calculadoras de teclado o editores donde el teclado forma parte del área de trabajo. iOS deja la decisión al desarrollador, proporcionando API flexibles para cualquier escenario.

Keyboard Frame Notifications

UIKeyboardWillShowNotification es la notificación principal que iOS envía antes de que aparezca el teclado. Contiene un CGRect con la posición final del teclado en el diccionario UIResponder.keyboardFrameEndUserInfoKey, así como la duración de la animación en UIResponder.keyboardAnimationDurationUserInfoKey.

El manejador de la notificación debe calcular la superposición entre el campo de texto activo y el teclado, luego cambiar el margen inferior (contentInset o frame) del contenedor. Si el campo está por debajo del borde superior del teclado, el contenido se desplaza hacia arriba en la cantidad de superposición. Al ocultarse el teclado, el margen vuelve a su 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
}

Al usar notificaciones, es importante manejar la animación de forma sincrónica con el teclado del sistema. iOS proporciona la curva de animación (UIResponder.keyboardAnimationCurveUserInfoKey) y la duración. Use UIView.animate con estos parámetros para que el contenido se desplace suavemente, al mismo tiempo que aparece el teclado.

Keyboard Layout Guide en iOS 15+

UIScrollView.keyboardLayoutGuide es una API moderna para Keyboard Avoidance, presentada en iOS 15. Rastrea automáticamente la posición del teclado y actualiza las restricciones de Auto Layout que conectan la parte inferior de la interfaz con el borde superior del teclado.

Para usarlo, simplemente active el layout guide en un UIScrollView o UIStackView y adjunte la restricción inferior del contenido al mismo. No se requiere trabajo manual con notificaciones, cálculo de altura ni animación — el sistema lo hace todo automáticamente, sincronizando la animación con la aparición y ocultación del teclado.

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

// Fijar restricción inferior a la parte superior del teclado
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard es una propiedad que determina si el guide debe responder a un teclado que puede desacoplarse del borde inferior (en iPad). Estabézcalo en true solo si la interfaz funciona correctamente con un teclado flotante. Para iPhone, esta propiedad se ignora — el teclado siempre está fijo en el borde inferior.

UIScrollView y el teclado

UIScrollView es un contenedor que Apple recomienda usar como base para Keyboard Avoidance. Cuando aparece el teclado, el scroll view aumenta su contentInset.bottom, permitiendo desplazar el contenido hacia arriba y hacer visible el campo activo.

El método clave es scrollRectToVisible, que desplaza programáticamente el scroll view para que el rectángulo especificado (el campo de texto activo) quede visible. Combinar el cambio de contentInset con una llamada a scrollRectToVisible garantiza que el campo no solo quede descubierto, sino que también se sitúe en la parte superior del área visible.

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 con UITableView, Apple recomienda usar UITableViewController, que ajusta automáticamente el contentInset cuando aparece el teclado. Si usa UIViewController con una tabla agregada, deberá implementar Keyboard Avoidance manualmente — UITableViewController no proporciona este comportamiento para controladores personalizados.

Auto Layout y Keyboard Avoidance

Auto Layout permite implementar Keyboard Avoidance sin programar animaciones — basta con cambiar la actividad (isActive) de una restricción específica o actualizar su constante en respuesta a una notificación del teclado.

Un esquema típico: crear un IBOutlet NSLayoutConstraint para el margen inferior del scroll view o contenido, y en el manejador keyboardWillShow establecer constraint.constant = keyboardHeight, y en keyboardWillHide restablecerlo a 0. Actualice el layout mediante layoutIfNeeded dentro de un bloque animate para una transición suave.

Al usar UIStackView, cambiar las restricciones del margen inferior también funciona: el stack view redistribuye los elementos hijos automáticamente. Sin embargo, si el stack view está dentro de un UIScrollView, es preferible gestionar el contentInset del propio scroll view, en lugar de las restricciones dentro de él.

Soluciones de terceros para Keyboard Avoidance

IQKeyboardManager es la biblioteca más popular (más de 16 000 estrellas en GitHub) que implementa Keyboard Avoidance automático sin una sola línea de código en el controlador. Utiliza method swizzling para rastrear los campos de texto y eleva automáticamente el contenido cuando aparece el teclado.

La biblioteca ofrece ajustes flexibles: puede especificar la distancia entre el campo y el teclado, activar/desactivar para controladores específicos y configurar el comportamiento para UITextView y vistas de entrada personalizadas. Sin embargo, el method swizzling puede entrar en conflicto con otras bibliotecas, y Apple no recomienda este enfoque para código de producción debido a efectos secundarios impredecibles.

Las alternativas incluyen TPKeyboardAvoiding (una biblioteca ligera, ~2000 estrellas) y KeyboardManager de la comunidad. Para proyectos modernos, Apple recomienda usar las herramientas integradas de iOS 15+, y para proyectos con una versión mínima más baja — UIScrollView con contentInset, que es la solución integrada más fiable.