Keyboard Avoidance — essentie, implementatiemethoden en interfaceverschuiving

Wat is Keyboard Avoidance

Keyboard Avoidance — is een verzameling technieken die de zichtbaarheid van het actieve invoerveld garanderen wanneer het systeemtoetsenbord op iOS verschijnt. Het basisprobleem: het toetsenbord neemt tot 50% van het scherm in beslag en bedekt de onderste helft van de interface, inclusief tekstvelden, verzendknoppen en andere elementen.

Er zijn drie hoofdbenaderingen voor implementatie: handmatig beheer via Keyboard Notifications (klassieke methode, werkt vanaf iOS 3.0), gebruik van UIScrollView met automatisch scrollen (aanbevolen door Apple) en Keyboard Layout Guide (moderne methode vanaf iOS 15+). De keuze hangt af van de minimale ondersteunde iOS-versie en de complexiteit van de interface.

Volgens Apple is het ontbreken van Keyboard Avoidance een van de meest voorkomende redenen voor afwijzing van apps bij beoordeling, als tekstvelden volledig worden bedekt door het toetsenbord. De App Store-richtlijnen vereisen expliciet dat alle interactieve elementen toegankelijk blijven tijdens actieve invoer.

Waarom iOS dit niet automatisch doet

iOS kan niet automatisch bepalen welk element zichtbaar moet blijven, omdat het de semantiek van de interface niet kent. In een eenvoudig formulier met één tekstveld is het voldoende om het hele scherm te verschuiven. In een complexe interface met aangepaste panelen, zwevende knoppen en meerdere secties is een andere gedragslogica vereist.

Bovendien verschuiven sommige apps opzettelijk geen inhoud — bijvoorbeeld toetsenbordrekenmachines of editors waar het toetsenbord deel uitmaakt van het werkgebied. iOS laat de beslissing aan de ontwikkelaar en biedt flexibele API's voor elk scenario.

Keyboard Frame Notifications

UIKeyboardWillShowNotification — de belangrijkste melding die iOS verzendt voordat het toetsenbord verschijnt. Het bevat een CGRect met de eindpositie van het toetsenbord in het woordenboek UIResponder.keyboardFrameEndUserInfoKey, evenals de animatieduur in UIResponder.keyboardAnimationDurationUserInfoKey.

De meldingshandler moet de overlapping tussen het actieve tekstveld en het toetsenbord berekenen en vervolgens de ondermarge (contentInset of frame) van de container wijzigen. Als het veld zich onder de bovenrand van het toetsenbord bevindt, wordt de inhoud omhoog verschoven met het bedrag van overlapping. Wanneer het toetsenbord wordt verborgen, keert de marge terug naar de oorspronkelijke waarde.

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

Bij het gebruik van meldingen is het belangrijk om de animatie te synchroniseren met het systeemtoetsenbord. iOS geeft de animatiecurve (UIResponder.keyboardAnimationCurveUserInfoKey) en duur door. Gebruik UIView.animate met deze parameters om de inhoud soepel te laten verschuiven, gelijktijdig met het verschijnen van het toetsenbord.

Keyboard Layout Guide in iOS 15+

UIScrollView.keyboardLayoutGuide — is een moderne API voor Keyboard Avoidance, geïntroduceerd in iOS 15. Het volgt automatisch de positie van het toetsenbord en werkt de Auto Layout-beperkingen bij die het onderste deel van de interface verbinden met de bovenrand van het toetsenbord.

Voor gebruik is het voldoende om de layout-guide in UIScrollView of UIStackView te activeren en de onderste beperking van de inhoud eraan te koppelen. Geen handmatig werk met meldingen, hoogteberekening en animatie is vereist — het systeem doet alles automatisch, waarbij de animatie wordt gesynchroniseerd met het verschijnen en verbergen van het toetsenbord.

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

// Bevestig onderste beperking aan bovenkant toetsenbord
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard — de eigenschap die bepaalt of de guide moet reageren op het toetsenbord dat kan worden losgekoppeld van de onderrand (op iPad). Stel dit alleen in op true als de interface correct werkt met een zwevend toetsenbord. Voor iPhone wordt deze eigenschap genegeerd — het toetsenbord is altijd aan de onderrand bevestigd.

UIScrollView en het toetsenbord

UIScrollView — is een container die Apple aanbeveelt als basis voor Keyboard Avoidance. Wanneer het toetsenbord verschijnt, vergroot de scrollview zijn contentInset.bottom, waardoor de inhoud omhoog kan scrollen en het actieve veld zichtbaar wordt.

De belangrijkste methode — scrollRectToVisible, die de scrollview programmatisch zodanig scrollt dat de opgegeven rechthoek (het actieve tekstveld) in het zichtbare gebied komt. Door de wijziging van contentInset te combineren met een aanroep van scrollRectToVisible, garandeert u dat het veld niet alleen niet wordt bedekt, maar zich in het bovenste deel van het zichtbare gebied bevindt.

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

Voor UIViewController met UITableView beveelt Apple het gebruik van UITableViewController aan, die automatisch de contentInset aanpast wanneer het toetsenbord verschijnt. Als u een UIViewController met een toegevoegde tabel gebruikt, moet u Keyboard Avoidance handmatig implementeren — UITableViewController biedt dit gedrag niet voor aangepaste controllers.

Auto Layout en Keyboard Avoidance

Auto Layout maakt het mogelijk om Keyboard Avoidance te implementeren zonder het programmeren van animaties — het is voldoende om de activiteit (isActive) van een bepaalde beperking te wijzigen of de constante ervan bij te werken als reactie op een toetsenbordmelding.

Typisch schema: maak een IBOutlet NSLayoutConstraint voor de ondermarge van de scrollview of inhoud, en stel in de keyboardWillShow-handler constraint.constant = keyboardHeight in, en in keyboardWillHide reset naar 0. Werk de lay-out bij via layoutIfNeeded binnen het animate-blok voor een soepele overgang.

Bij gebruik van UIStackView werken wijzigingen in de beperkingen van de ondermarge ook: de stackview verdeelt de onderliggende elementen automatisch opnieuw. Als de stackview zich echter in een UIScrollView bevindt, verdient het de voorkeur om de contentInset van de scrollview zelf te beheren, niet de beperkingen erin.

Externe oplossingen voor Keyboard Avoidance

IQKeyboardManager — de populairste bibliotheek (meer dan 16.000 sterren op GitHub) die automatische Keyboard Avoidance implementeert zonder een enkele regel code in de controller. Het gebruikt method swizzling om tekstvelden te volgen en verhoogt automatisch de inhoud wanneer het toetsenbord verschijnt.

De bibliotheek biedt flexibele instellingen: u kunt de afstand tussen het veld en het toetsenbord opgeven, in-/uitschakelen voor afzonderlijke controllers, het gedrag configureren voor UITextView en aangepaste invoerweergaven. Method swizzling kan echter conflicteren met andere bibliotheken en Apple raadt deze benadering niet aan voor productiecode vanwege onvoorspelbare bijwerkingen.

Alternatieven zijn TPKeyboardAvoiding(lichte bibliotheek, ~2000 sterren) en KeyboardManager van de community. Voor moderne projecten beveelt Apple het gebruik van ingebouwde iOS 15+-tools aan, en voor projecten met een lagere minimale versie — UIScrollView met contentInset, wat de meest betrouwbare ingebouwde oplossing is.