Keyboard Avoidance — същност, начини за имплементация и изместване на интерфейса

Какво е Keyboard Avoidance

Keyboard Avoidance — е набор от техники, които осигуряват видимостта на активното поле за въвеждане при появата на системната клавиатура на iOS. Основният проблем: клавиатурата заема до 50% от екрана и покрива долната половина на интерфейса, включително текстови полета, бутони за изпращане и други елементи.

Съществуват три основни подхода за имплементация: ръчно управление чрез Keyboard Notifications (класически метод, работи от iOS 3.0), използване на UIScrollView с автоматично скролване (препоръчвано от Apple) и Keyboard Layout Guide (модерен метод от iOS 15+). Изборът зависи от минималната поддържана версия на iOS и сложността на интерфейса.

Според Apple, липсата на Keyboard Avoidance е една от най-честите причини за отхвърляне на приложения при преглед, ако текстовите полета са напълно покрити от клавиатурата. Насоките на App Store изрично изискват всички интерактивни елементи да останат достъпни по време на активно въвеждане.

Защо iOS не прави това автоматично

iOS не може автоматично да определи кой елемент трябва да остане видим, тъй като не познава семантиката на интерфейса. В проста форма с едно текстово поле е достатъчно да се премести целият екран. В сложен интерфейс с персонализирани панели, плаващи бутони и множество секции се изисква различна логика на поведение.

Освен това някои приложения умишлено не изместват съдържанието — например клавиатурни калкулатори или редактори, където клавиатурата е част от работната област. iOS оставя решението на разработчика, предоставяйки гъвкави API за всеки сценарий.

Keyboard Frame Notifications

UIKeyboardWillShowNotification — основното известие, което iOS изпраща преди появата на клавиатурата. Съдържа CGRect с крайната позиция на клавиатурата в речника UIResponder.keyboardFrameEndUserInfoKey, както и продължителността на анимацията в UIResponder.keyboardAnimationDurationUserInfoKey.

Обработчикът на известието трябва да изчисли припокриването между активното текстово поле и клавиатурата, след което да промени долния маржин (contentInset или frame) на контейнера. Ако полето е под горния ръб на клавиатурата, съдържанието се измества нагоре с размера на припокриването. При скриване на клавиатурата маржинът се връща към първоначалната стойност.

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

При използване на известия е важно да синхронизирате анимацията със системната клавиатура. iOS предава кривата на анимация (UIResponder.keyboardAnimationCurveUserInfoKey) и продължителността. Използвайте UIView.animate с тези параметри, така че съдържанието да се измества плавно, едновременно с появата на клавиатурата.

Keyboard Layout Guide в iOS 15+

UIScrollView.keyboardLayoutGuide — е модерен API за Keyboard Avoidance, въведен в iOS 15. Той автоматично следи позицията на клавиатурата и актуализира Auto Layout ограниченията, свързващи долната част на интерфейса с горния ръб на клавиатурата.

За използване е достатъчно да активирате layout guide в UIScrollView или UIStackView и да свържете долното ограничение на съдържанието към него. Не е необходима ръчна работа с известия, изчисляване на височина и анимация — системата прави всичко автоматично, синхронизирайки анимацията с появата и скриването на клавиатурата.

// Активирайте Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// Закрепете долното ограничение към горната част на клавиатурата
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — свойството, което определя дали guide трябва да реагира на клавиатура, която може да бъде отделена от долния ръб (на iPad). Задайте true само ако интерфейсът работи правилно с плаваща клавиатура. За iPhone това свойство се игнорира — клавиатурата винаги е прикрепена към долния ръб.

UIScrollView и клавиатурата

UIScrollView — е контейнер, който Apple препоръчва като основа за Keyboard Avoidance. Когато клавиатурата се появи, scroll view увеличава своя contentInset.bottom, позволявайки превъртане на съдържанието нагоре и правейки активното поле видимо.

Ключовият метод — scrollRectToVisible, който програмно превърта scroll view така, че зададеният правоъгълник (активно текстово поле) да се намира във видимата област. Комбинирайки промяната на contentInset с извикването на scrollRectToVisible, гарантирате, че полето не само не е покрито, но се намира в горната част на видимата област.

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

За UIViewController с UITableView Apple препоръчва използването на UITableViewController, който автоматично коригира contentInset при появата на клавиатурата. Ако използвате UIViewController с добавена таблица, ще трябва да имплементирате Keyboard Avoidance ръчно — UITableViewController не предоставя това поведение за персонализирани контролери.

Auto Layout и Keyboard Avoidance

Auto Layout позволява имплементиране на Keyboard Avoidance без програмиране на анимации — достатъчно е да промените активността (isActive) на определено ограничение или да актуализирате неговата константа в отговор на известие от клавиатурата.

Типична схема: създайте IBOutlet NSLayoutConstraint за долния маржин на scroll view или съдържанието и в обработчика keyboardWillShow задайте constraint.constant = keyboardHeight, а в keyboardWillHide нулирайте на 0. Актуализирайте оформлението чрез layoutIfNeeded в рамките на animate блока за плавен преход.

При използване на UIStackView промените на ограниченията на долния маржин също работят: stack view автоматично преразпределя дъщерните елементи. Въпреки това, ако stack view се намира вътре в UIScrollView, за предпочитане е да управлявате contentInset на самия scroll view, а не ограниченията вътре в него.

Решения на трети страни за Keyboard Avoidance

IQKeyboardManager — най-популярната библиотека (над 16 000 звезди в GitHub), която имплементира автоматично Keyboard Avoidance без нито един ред код в контролера. Тя използва method swizzling за проследяване на текстови полета и автоматично повдига съдържанието при появата на клавиатурата.

Библиотеката предоставя гъвкави настройки: можете да зададете разстоянието между полето и клавиатурата, да включите/изключите за отделни контролери, да конфигурирате поведението за UITextView и персонализирани изгледи за въвеждане. Въпреки това, method swizzling може да влезе в конфликт с други библиотеки и Apple не препоръчва този подход за производствен код поради непредвидими странични ефекти.

Алтернативите включват TPKeyboardAvoiding (лека библиотека, ~2000 звезди) и KeyboardManager от общността. За съвременни проекти Apple препоръчва използването на вградените инструменти на iOS 15+, а за проекти с по-ниска минимална версия — UIScrollView с contentInset, който е най-надеждното вградено решение.