Keyboard Avoidance — esența, metodele de implementare și deplasarea interfeței

Ce este Keyboard Avoidance

Keyboard Avoidance — este un set de tehnici care asigură vizibilitatea câmpului de introducere activ la apariția tastaturii sistemului pe iOS. Problema de bază: tastatura ocupă până la 50% din ecran și acoperă jumătatea inferioară a interfeței, inclusiv câmpurile text, butoanele de trimitere și alte elemente.

Există trei abordări principale de implementare: gestionarea manuală prin Keyboard Notifications (metodă clasică, funcționează din iOS 3.0), utilizarea UIScrollView cu derulare automată (recomandată de Apple) și Keyboard Layout Guide (metodă modernă din iOS 15+). Alegerea depinde de versiunea minimă suportată de iOS și de complexitatea interfeței.

Potrivit Apple, lipsa Keyboard Avoidance este una dintre cele mai frecvente cauze de respingere a aplicațiilor la revizuire, dacă câmpurile text sunt complet acoperite de tastatură. Ghidurile App Store cer în mod explicit ca toate elementele interactive să rămână accesibile în timpul introducerii active.

De ce iOS nu face acest lucru automat

iOS nu poate determina automat care element ar trebui să rămână vizibil, deoarece nu cunoaște semantica interfeței. Într-un formular simplu cu un singur câmp text, este suficient să deplasați întregul ecran. Într-o interfață complexă cu panouri personalizate, butoane plutitoare și mai multe secțiuni, este necesară o logică de comportament diferită.

În plus, unele aplicații nu deplasează intenționat conținutul — de exemplu, calculatoarele cu tastatură sau editorii în care tastatura face parte din zona de lucru. iOS lasă decizia dezvoltatorului, oferind API-uri flexibile pentru orice scenariu.

Keyboard Frame Notifications

UIKeyboardWillShowNotification — notificarea principală pe care iOS o trimite înainte de apariția tastaturii. Conține CGRect cu poziția finală a tastaturii în dicționarul UIResponder.keyboardFrameEndUserInfoKey, precum și durata animației în UIResponder.keyboardAnimationDurationUserInfoKey.

Handler-ul notificării trebuie să calculeze suprapunerea dintre câmpul text activ și tastatură, apoi să modifice marginea inferioară (contentInset sau frame) a containerului. Dacă câmpul se află sub marginea superioară a tastaturii, conținutul se deplasează în sus cu valoarea suprapunerii. La ascunderea tastaturii, marginea revine la valoarea inițială.

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

La utilizarea notificărilor, este important să sincronizați animația cu tastatura sistemului. iOS transmite curba de animație (UIResponder.keyboardAnimationCurveUserInfoKey) și durata. Utilizați UIView.animate cu acești parametri pentru ca conținutul să se deplaseze lin, simultan cu apariția tastaturii.

Keyboard Layout Guide în iOS 15+

UIScrollView.keyboardLayoutGuide — este un API modern pentru Keyboard Avoidance, introdus în iOS 15. Urmărește automat poziția tastaturii și actualizează constrângerile Auto Layout care leagă partea inferioară a interfeței de marginea superioară a tastaturii.

Pentru utilizare, este suficient să activați layout guide în UIScrollView sau UIStackView și să legați constrângerea inferioară a conținutului de acesta. Nicio muncă manuală cu notificări, calcularea înălțimii și animație nu este necesară — sistemul face totul automat, sincronizând animația cu apariția și ascunderea tastaturii.

// Activați Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// Fixați constrângerea inferioară la partea de sus a tastaturii
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — proprietatea care determină dacă ghidul trebuie să reacționeze la tastatura care poate fi deconectată de la marginea inferioară (pe iPad). Setați true doar dacă interfața funcționează corect cu tastatura plutitoare. Pentru iPhone, această proprietate este ignorată — tastatura este întotdeauna atașată de marginea inferioară.

UIScrollView și tastatura

UIScrollView — este un container pe care Apple îl recomandă ca bază pentru Keyboard Avoidance. Când tastatura apare, scroll view își mărește contentInset.bottom, permițând derularea conținutului în sus și făcând câmpul activ vizibil.

Metoda cheie — scrollRectToVisible, care derulează programatic scroll view-ul astfel încât dreptunghiul specificat (câmpul text activ) să se afle în zona vizibilă. Combinând modificarea contentInset cu apelarea scrollRectToVisible, garantați că câmpul nu este doar neacoperit, ci se află în partea superioară a zonei vizibile.

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

Pentru UIViewController cu UITableView, Apple recomandă utilizarea UITableViewController, care ajustează automat contentInset la apariția tastaturii. Dacă utilizați UIViewController cu un tabel adăugat, va trebui să implementați Keyboard Avoidance manual — UITableViewController nu oferă acest comportament pentru controlere personalizate.

Auto Layout și Keyboard Avoidance

Auto Layout permite implementarea Keyboard Avoidance fără programarea animațiilor — este suficient să schimbați activitatea (isActive) unei anumite constrângeri sau să actualizați constanta acesteia ca răspuns la notificarea tastaturii.

Schema tipică: creați un IBOutlet NSLayoutConstraint pentru marginea inferioară a scroll view-ului sau conținutului, iar în handler-ul keyboardWillShow setați constraint.constant = keyboardHeight, iar în keyboardWillHide resetați la 0. Actualizați layout-ul prin layoutIfNeeded în interiorul blocului animate pentru o tranziție lină.

La utilizarea UIStackView, modificările constrângerilor marginii inferioare funcționează de asemenea: stack view redistribuie automat elementele copil. Cu toate acestea, dacă stack view se află în interiorul unui UIScrollView, este preferabil să gestionați contentInset al scroll view-ului însuși, nu constrângerile din interiorul acestuia.

Soluții terțe pentru Keyboard Avoidance

IQKeyboardManager — cea mai populară bibliotecă (peste 16.000 de stele pe GitHub) care implementează Keyboard Avoidance automat fără o singură linie de cod în controler. Utilizează method swizzling pentru urmărirea câmpurilor text și ridică automat conținutul la apariția tastaturii.

Biblioteca oferă setări flexibile: puteți specifica distanța dintre câmp și tastatură, activa/dezactiva pentru controlere individuale, configura comportamentul pentru UITextView și input view-uri personalizate. Cu toate acestea, method swizzling poate intra în conflict cu alte biblioteci, iar Apple nu recomandă această abordare pentru codul de producție din cauza efectelor secundare imprevizibile.

Alternativele includ TPKeyboardAvoiding (bibliotecă ușoară, ~2000 de stele) și KeyboardManager din comunitate. Pentru proiecte moderne, Apple recomandă utilizarea instrumentelor încorporate iOS 15+, iar pentru proiecte cu o versiune minimă mai mică — UIScrollView cu contentInset, care este cea mai fiabilă soluție încorporată.