Keyboard Avoidance — istota, metody implementacji i przesunięcie interfejsu

Co to jest Keyboard Avoidance

Keyboard Avoidance — to zbiór technik zapewniających widoczność aktywnego pola wprowadzania po pojawieniu się klawiatury systemowej na iOS. Podstawowy problem: klawiatura zajmuje do 50% ekranu i zasłania dolną połowę interfejsu, w tym pola tekstowe, przyciski wysyłania i inne elementy.

Istnieją trzy główne podejścia do implementacji: ręczne zarządzanie przez Keyboard Notifications (klasyczna metoda, działa od iOS 3.0), użycie UIScrollView z automatycznym przewijaniem (zalecane przez Apple) oraz Keyboard Layout Guide (nowoczesna metoda od iOS 15+). Wybór zależy od minimalnej obsługiwanej wersji iOS i złożoności interfejsu.

Według Apple, brak Keyboard Avoidance jest jedną z najczęstszych przyczyn odrzucania aplikacji podczas recenzji, jeśli pola tekstowe są całkowicie zasłonięte przez klawiaturę. Wytyczne App Store wyraźnie wymagają, aby wszystkie elementy interaktywne pozostały dostępne podczas aktywnego wprowadzania.

Dlaczego iOS nie robi tego automatycznie

iOS nie może automatycznie określić, który element powinien pozostać widoczny, ponieważ nie zna semantyki interfejsu. W prostym formularzu z jednym polem tekstowym wystarczy przesunąć cały ekran. W złożonym interfejsie z niestandardowymi panelami, pływającymi przyciskami i wieloma sekcjami wymagana jest inna logika zachowania.

Ponadto niektóre aplikacje celowo nie przesuwają treści — na przykład kalkulatory klawiaturowe lub edytory, gdzie klawiatura jest częścią obszaru roboczego. iOS pozostawia decyzję programiście, dostarczając elastyczne API dla każdego scenariusza.

Keyboard Frame Notifications

UIKeyboardWillShowNotification — podstawowe powiadomienie, które iOS wysyła przed pojawieniem się klawiatury. Zawiera CGRect z końcową pozycją klawiatury w słowniku UIResponder.keyboardFrameEndUserInfoKey, a także czas trwania animacji w UIResponder.keyboardAnimationDurationUserInfoKey.

Handler powiadomienia powinien obliczyć nakładanie między aktywnym polem tekstowym a klawiaturą, a następnie zmienić dolny odstęp (contentInset lub frame) kontenera. Jeśli pole znajduje się poniżej górnej krawędzi klawiatury, treść przesuwa się w górę o wielkość nakładania. Przy ukrywaniu klawiatury odstęp wraca do pierwotnej wartości.

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

Przy użyciu powiadomień ważne jest synchronizowanie animacji z systemową klawiaturą. iOS przekazuje krzywą animacji (UIResponder.keyboardAnimationCurveUserInfoKey) i czas trwania. Użyj UIView.animate z tymi parametrami, aby treść przesuwała się płynnie, jednocześnie z pojawieniem się klawiatury.

Keyboard Layout Guide w iOS 15+

UIScrollView.keyboardLayoutGuide — to nowoczesne API do Keyboard Avoidance, wprowadzone w iOS 15. Automatycznie śledzi pozycję klawiatury i aktualizuje ograniczenia Auto Layout, łączące dolną część interfejsu z górną krawędzią klawiatury.

Do użycia wystarczy aktywować layout guide w UIScrollView lub UIStackView i przypiąć do niego dolne ograniczenie treści. Żadnej ręcznej pracy z powiadomieniami, obliczaniem wysokości i animacją — system robi wszystko automatycznie, synchronizując animację z pojawianiem się i ukrywaniem klawiatury.

// Włącz Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// Przypnij dolne ograniczenie do góry klawiatury
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — właściwość określająca, czy guide ma reagować na klawiaturę, która może być odłączona od dolnej krawędzi (na iPadzie). Ustaw true, tylko jeśli interfejs działa poprawnie z pływającą klawiaturą. Dla iPhone ta właściwość jest ignorowana — klawiatura jest zawsze przymocowana do dolnej krawędzi.

UIScrollView i klawiatura

UIScrollView — to kontener, który Apple zaleca używać jako podstawę dla Keyboard Avoidance. Kiedy klawiatura się pojawia, scroll view zwiększa swój contentInset.bottom, umożliwiając przewinięcie treści w górę i uczynienie aktywnego pola widocznym.

Kluczowa metoda — scrollRectToVisible, która programowo przewija scroll view tak, aby określony prostokąt (aktywne pole tekstowe) znalazł się w widocznym obszarze. Łącząc zmianę contentInset z wywołaniem scrollRectToVisible, gwarantujesz, że pole nie tylko nie jest zasłonięte, ale znajduje się w górnej części widocznego obszaru.

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

Dla UIViewController z UITableView Apple zaleca używanie UITableViewController, który automatycznie koryguje contentInset po pojawieniu się klawiatury. Jeśli używasz UIViewController z dodaną tabelą, musisz zaimplementować Keyboard Avoidance ręcznie — UITableViewController nie zapewnia tego zachowania dla niestandardowych kontrolerów.

Auto Layout i Keyboard Avoidance

Auto Layout pozwala zaimplementować Keyboard Avoidance bez programowania animacji — wystarczy zmienić aktywność (isActive) określonego ograniczenia lub zaktualizować jego stałą w odpowiedzi na powiadomienie klawiatury.

Typowy schemat: utwórz IBOutlet NSLayoutConstraint dla dolnego odstępu scroll view lub treści, a w handlerze keyboardWillShow ustaw constraint.constant = keyboardHeight, a w keyboardWillHide — zresetuj do 0. Zaktualizuj layout przez layoutIfNeeded wewnątrz bloku animate dla płynnego przejścia.

Przy użyciu UIStackView zmiany ograniczeń dolnego odstępu również działają: stack view automatycznie rozdziela elementy potomne. Jeśli jednak stack view znajduje się wewnątrz UIScrollView, lepiej zarządzać contentInset samego scroll view, a nie ograniczeniami wewnątrz niego.

Rozwiązania zewnętrzne dla Keyboard Avoidance

IQKeyboardManager — najpopularniejsza biblioteka (ponad 16 000 gwiazdek na GitHub), która implementuje automatyczny Keyboard Avoidance bez ani jednej linii kodu w kontrolerze. Używa method swizzling do śledzenia pól tekstowych i automatycznie podnosi treść po pojawieniu się klawiatury.

Biblioteka oferuje elastyczne ustawienia: można określić odległość między polem a klawiaturą, włączyć/wyłączyć dla poszczególnych kontrolerów, skonfigurować zachowanie dla UITextView i niestandardowych input view. Jednak method swizzling może kolidować z innymi bibliotekami, a Apple nie zaleca tego podejścia dla kodu produkcyjnego ze względu na nieprzewidywalne efekty uboczne.

Alternatywy obejmują TPKeyboardAvoiding (lekka biblioteka, ~2000 gwiazdek) i KeyboardManager od społeczności. Dla nowoczesnych projektów Apple zaleca używanie wbudowanych narzędzi iOS 15+, a dla projektów z niższą minimalną wersją — UIScrollView z contentInset, który jest najbardziej niezawodnym wbudowanym rozwiązaniem.