Keyboard Avoidance — essenza, metodi di implementazione e offset dell’interfaccia

Cos’è Keyboard Avoidance

Keyboard Avoidance è un insieme di tecniche che garantiscono la visibilità del campo di input attivo quando appare la tastiera di sistema su iOS. Il problema di base: la tastiera occupa fino al 50% dello schermo e copre la metà inferiore dell’interfaccia, inclusi campi di testo, pulsanti di invio e altri elementi.

Esistono tre approcci principali all’implementazione: gestione manuale tramite Keyboard Notifications (metodo classico, funziona da iOS 3.0), uso di UIScrollView con scorrimento automatico (raccomandato da Apple) e Keyboard Layout Guide (metodo moderno con iOS 15+). La scelta dipende dalla versione minima supportata di iOS e dalla complessità dell’interfaccia.

Secondo Apple, la mancanza di Keyboard Avoidance è una delle cause più comuni di rifiuto dell’app durante la revisione se i campi di testo sono completamente coperti dalla tastiera. Le App Store Guidelines richiedono esplicitamente che tutti gli elementi interattivi rimangano accessibili durante l’input attivo.

Perché iOS non lo fa automaticamente

iOS non può determinare automaticamente quale elemento deve rimanere visibile perché non conosce la semantica dell’interfaccia. In un modulo semplice con un campo di testo, è sufficiente spostare l’intero schermo verso l’alto. In un’interfaccia complessa con pannelli personalizzati, pulsanti fluttuanti e sezioni multiple, è necessaria una logica di comportamento diversa.

Inoltre, alcune app non spostano intenzionalmente il contenuto — ad esempio, calcolatrici da tastiera o editor in cui la tastiera fa parte dell’area di lavoro. iOS lascia la decisione allo sviluppatore, fornendo API flessibili per qualsiasi scenario.

Notifiche del frame della tastiera

UIKeyboardWillShowNotification è la notifica principale che iOS invia prima della comparsa della tastiera. Contiene un CGRect con la posizione finale della tastiera nel dizionario UIResponder.keyboardFrameEndUserInfoKey, oltre alla durata dell’animazione in UIResponder.keyboardAnimationDurationUserInfoKey.

Il gestore della notifica deve calcolare la sovrapposizione tra il campo di testo attivo e la tastiera, quindi modificare il margine inferiore (contentInset o frame) del contenitore. Se il campo si trova al di sotto del bordo superiore della tastiera, il contenuto si sposta verso l’alto della quantità di sovrapposizione. Quando la tastiera si nasconde, il margine torna al suo valore originale.

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

Quando si utilizzano le notifiche, è importante gestire l’animazione in modo sincrono con la tastiera di sistema. iOS fornisce la curva di animazione (UIResponder.keyboardAnimationCurveUserInfoKey) e la durata. Usa UIView.animate con questi parametri in modo che il contenuto si sposti gradualmente, contemporaneamente alla comparsa della tastiera.

Keyboard Layout Guide in iOS 15+

UIScrollView.keyboardLayoutGuide è un’API moderna per Keyboard Avoidance, introdotta in iOS 15. Tiene traccia automaticamente della posizione della tastiera e aggiorna i vincoli Auto Layout che collegano la parte inferiore dell’interfaccia al bordo superiore della tastiera.

Per utilizzarla, basta attivare la guida di layout su un UIScrollView o UIStackView e collegare ad essa il vincolo inferiore del contenuto. Nessun lavoro manuale con notifiche, calcolo dell’altezza o animazione è necessario — il sistema fa tutto automaticamente, sincronizzando l’animazione con la comparsa e la scomparsa della tastiera.

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

// Fissa il vincolo inferiore alla parte superiore della tastiera
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard è una proprietà che determina se la guida deve rispondere a una tastiera che può essere staccata dal bordo inferiore (su iPad). Impostala su true solo se l’interfaccia funziona correttamente con una tastiera fluttuante. Per iPhone, questa proprietà viene ignorata — la tastiera è sempre fissata al bordo inferiore.

UIScrollView e la tastiera

UIScrollView è un contenitore che Apple raccomanda di utilizzare come base per Keyboard Avoidance. Quando la tastiera appare, la scroll view aumenta il suo contentInset.bottom, permettendo di scorrere il contenuto verso l’alto e rendere visibile il campo attivo.

Il metodo chiave è scrollRectToVisible, che scorre programmaticamente la scroll view in modo che il rettangolo specificato (il campo di testo attivo) si trovi nell’area visibile. Combinare la modifica del contentInset con una chiamata a scrollRectToVisible garantisce che il campo non solo sia scoperto ma anche posizionato nella parte superiore dell’area visibile.

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

Per UIViewController con UITableView, Apple raccomanda di utilizzare UITableViewController, che regola automaticamente il contentInset alla comparsa della tastiera. Se utilizzi UIViewController con una tabella aggiunta, dovrai implementare Keyboard Avoidance manualmente — UITableViewController non fornisce questo comportamento per controller personalizzati.

Auto Layout e Keyboard Avoidance

Auto Layout permette di implementare Keyboard Avoidance senza programmare animazioni — basta modificare l’attività (isActive) di un vincolo specifico o aggiornare la sua costante in risposta a una notifica della tastiera.

Uno schema tipico: creare un IBOutlet NSLayoutConstraint per il margine inferiore della scroll view o del contenuto, e nel gestore keyboardWillShow impostare constraint.constant = keyboardHeight, e in keyboardWillHide azzerarlo. Aggiorna il layout tramite layoutIfNeeded all’interno di un blocco animate per una transizione fluida.

Quando si utilizza UIStackView, anche la modifica dei vincoli del margine inferiore funziona: la stack view ridistribuisce automaticamente gli elementi figli. Tuttavia, se la stack view si trova all’interno di un UIScrollView, è preferibile gestire il contentInset della scroll view stessa, piuttosto che i vincoli al suo interno.

Soluzioni di terze parti per Keyboard Avoidance

IQKeyboardManager è la libreria più popolare (oltre 16.000 stelle su GitHub) che implementa Keyboard Avoidance automatico senza una singola riga di codice nel controller. Utilizza il method swizzling per tracciare i campi di testo e solleva automaticamente il contenuto alla comparsa della tastiera.

La libreria offre impostazioni flessibili: puoi specificare la distanza tra il campo e la tastiera, abilitare/disabilitare per controller specifici e configurare il comportamento per UITextView e viste di input personalizzate. Tuttavia, il method swizzling può entrare in conflitto con altre librerie e Apple non raccomanda questo approccio per il codice di produzione a causa di effetti collaterali imprevedibili.

Le alternative includono TPKeyboardAvoiding (una libreria leggera, ~2.000 stelle) e KeyboardManager della comunità. Per i progetti moderni, Apple raccomanda di utilizzare gli strumenti integrati di iOS 15+, e per i progetti con una versione minima inferiore — UIScrollView con contentInset, che è la soluzione integrata più affidabile.