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 Guidelines чітко вимагають, щоб всі інтерактивні елементи залишалися доступними під час активного введення.

Чому iOS не робить це автоматично

iOS не може автоматично визначити, який елемент повинен залишатися видимим, оскільки не знає семантики інтерфейсу. У простій формі з одним текстовим полем достатньо перемістити весь екран вгору. У складному інтерфейсі з кастомними панелями, плаваючими кнопками та кількома розділами потрібна інша логіка поведінки.

Крім того, деякі додатки навмисно не зміщують контент — наприклад, клавіатурні калькулятори або редактори, де клавіатура є частиною робочої області. iOS залишає рішення розробнику, надаючи гнучкі API для будь-якого сценарію.

Сповіщення про рамку клавіатури

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 — властивість, яка визначає, чи повинен гайд реагувати на клавіатуру, яку можна відокремити від нижнього краю (на 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, який є найнадійнішим вбудованим рішенням.