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 не может автоматически определить, какой элемент должен оставаться видимым, потому что не знает семантики интерфейса. В простой форме с одним текстовым полем достаточно подвинуть весь экран. В сложном интерфейсе с кастомными панелями, floating-кнопками и несколькими секциями требуется разная логика поведения.

Кроме того, некоторые приложения намеренно не смещают контент — например, клавиатурные калькуляторы или редакторы, где клавиатура является частью рабочей области. 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 constraints, связывающие нижнюю часть интерфейса с верхней границей клавиатуры.

Для использования достаточно активировать layout guide у UIScrollView или UIStackView и привязать к нему нижний констрейнт контента. Никакой ручной работы с уведомлениями, вычислением высоты и анимацией не требуется — система делает всё автоматически, синхронизируя анимацию с появлением и скрытием клавиатуры.

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

// Pin bottom constraint to keyboard top
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. Обновите layout через layoutIfNeeded внутри animate-блока для плавного перехода.

При использовании UIStackView изменения констрейнтов нижнего отступа также работают: stack view перераспределяет дочерние элементы автоматически. Однако если stack view находится внутри UIScrollView, предпочтительнее управлять contentInset самого scroll view, а не констрейнтами внутри него.

Сторонние решения для Keyboard Avoidance

IQKeyboardManager — самая популярная библиотека (более 16 000 stars на GitHub), которая реализует автоматический Keyboard Avoidance без единой строки кода в контроллере. Она использует method swizzling для отслеживания текстовых полей и автоматически поднимает контент при появлении клавиатуры.

Библиотека предоставляет гибкие настройки: можно указать расстояние между полем и клавиатурой, включить/отключить для отдельных контроллеров, настроить поведение для UITextView и кастомных input view. Однако method swizzling может конфликтовать с другими библиотеками, и Apple не рекомендует этот подход для production-кода из-за непредсказуемых side-эффектов.

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