Keyboard Avoidance — essence, méthodes d’implémentation et décalage de l’interface

Qu’est-ce que Keyboard Avoidance

Keyboard Avoidance est un ensemble de techniques garantissant la visibilité du champ de saisie actif lors de l’apparition du clavier système sur iOS. Le problème de base : le clavier occupe jusqu’à 50 % de l’écran et couvre la moitié inférieure de l’interface, y compris les champs de texte, les boutons d’envoi et d’autres éléments.

Il existe trois approches principales pour la mise en œuvre : la gestion manuelle via les Keyboard Notifications (méthode classique, fonctionne depuis iOS 3.0), l’utilisation de UIScrollView avec défilement automatique (recommandée par Apple) et le Keyboard Layout Guide (méthode moderne avec iOS 15+). Le choix dépend de la version minimale prise en charge d’iOS et de la complexité de l’interface.

Selon Apple, l’absence de Keyboard Avoidance est l’une des causes les plus fréquentes de rejet d’application lors de la révision si les champs de texte sont complètement recouverts par le clavier. Les App Store Guidelines exigent explicitement que tous les éléments interactifs restent accessibles pendant la saisie active.

Pourquoi iOS ne le fait-il pas automatiquement

iOS ne peut pas déterminer automatiquement quel élément doit rester visible car il ne connaît pas la sémantique de l’interface. Dans un formulaire simple avec un champ de texte, il suffit de déplacer tout l’écran vers le haut. Dans une interface complexe avec des panneaux personnalisés, des boutons flottants et plusieurs sections, une logique de comportement différente est nécessaire.

De plus, certaines applications ne décalent pas intentionnellement le contenu — par exemple, les calculateurs de clavier ou les éditeurs où le clavier fait partie de l’espace de travail. iOS laisse la décision au développeur, en fournissant des API flexibles pour tout scénario.

Notifications de cadre du clavier

UIKeyboardWillShowNotification est la notification principale qu’iOS envoie avant l’apparition du clavier. Elle contient un CGRect avec la position finale du clavier dans le dictionnaire UIResponder.keyboardFrameEndUserInfoKey, ainsi que la durée de l’animation dans UIResponder.keyboardAnimationDurationUserInfoKey.

Le gestionnaire de notification doit calculer le chevauchement entre le champ de texte actif et le clavier, puis modifier la marge inférieure (contentInset ou frame) du conteneur. Si le champ se trouve en dessous du bord supérieur du clavier, le contenu se décale vers le haut de la quantité de chevauchement. Lorsque le clavier se masque, la marge revient à sa valeur d’origine.

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

Lors de l’utilisation de notifications, il est important de gérer l’animation de manière synchrone avec le clavier système. iOS fournit la courbe d’animation (UIResponder.keyboardAnimationCurveUserInfoKey) et la durée. Utilisez UIView.animate avec ces paramètres pour que le contenu se déplace en douceur, simultanément à l’apparition du clavier.

Keyboard Layout Guide dans iOS 15+

UIScrollView.keyboardLayoutGuide est une API moderne pour Keyboard Avoidance, introduite dans iOS 15. Elle suit automatiquement la position du clavier et met à jour les contraintes Auto Layout qui relient la partie inférieure de l’interface au bord supérieur du clavier.

Pour l’utiliser, il suffit d’activer le guide de mise en page sur un UIScrollView ou UIStackView et d’y attacher la contrainte inférieure du contenu. Aucun travail manuel avec les notifications, le calcul de hauteur ou l’animation n’est nécessaire — le système fait tout automatiquement, en synchronisant l’animation avec l’apparition et le masquage du clavier.

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

// Fixer la contrainte inférieure au sommet du clavier
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard est une propriété qui détermine si le guide doit répondre à un clavier pouvant être détaché du bord inférieur (sur iPad). Définissez-la sur true uniquement si l’interface fonctionne correctement avec un clavier flottant. Pour iPhone, cette propriété est ignorée — le clavier est toujours fixé au bord inférieur.

UIScrollView et le clavier

UIScrollView est un conteneur qu’Apple recommande d’utiliser comme base pour Keyboard Avoidance. Lorsque le clavier apparaît, la vue de défilement augmente son contentInset.bottom, permettant de faire défiler le contenu vers le haut et de rendre le champ actif visible.

La méthode clé est scrollRectToVisible, qui fait défiler programmatiquement la vue de défilement pour que le rectangle spécifié (le champ de texte actif) se trouve dans la zone visible. Combiner la modification du contentInset avec un appel à scrollRectToVisible garantit que le champ est non seulement découvert mais aussi positionné dans la partie supérieure de la zone visible.

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

Pour UIViewController avec UITableView, Apple recommande d’utiliser UITableViewController, qui ajuste automatiquement le contentInset lors de l’apparition du clavier. Si vous utilisez UIViewController avec une table ajoutée, vous devrez implémenter Keyboard Avoidance manuellement — UITableViewController ne fournit pas ce comportement pour les contrôleurs personnalisés.

Auto Layout et Keyboard Avoidance

Auto Layout permet d’implémenter Keyboard Avoidance sans programmer d’animations — il suffit de modifier l’activité (isActive) d’une contrainte spécifique ou de mettre à jour sa constante en réponse à une notification du clavier.

Un schéma typique : créer une IBOutlet NSLayoutConstraint pour la marge inférieure de la vue de défilement ou du contenu, et dans le gestionnaire keyboardWillShow définir constraint.constant = keyboardHeight, et dans keyboardWillHide la réinitialiser à 0. Mettez à jour la mise en page via layoutIfNeeded dans un bloc animate pour une transition fluide.

Lors de l’utilisation de UIStackView, la modification des contraintes de marge inférieure fonctionne également : la vue en pile redistribue les éléments enfants automatiquement. Cependant, si la vue en pile se trouve à l’intérieur d’un UIScrollView, il est préférable de gérer le contentInset de la vue de défilement elle-même, plutôt que les contraintes à l’intérieur de celle-ci.

Solutions tierces pour Keyboard Avoidance

IQKeyboardManager est la bibliothèque la plus populaire (plus de 16 000 étoiles sur GitHub) qui implémente le Keyboard Avoidance automatique sans une seule ligne de code dans le contrôleur. Elle utilise le method swizzling pour suivre les champs de texte et élève automatiquement le contenu lors de l’apparition du clavier.

La bibliothèque offre des paramètres flexibles : vous pouvez spécifier la distance entre le champ et le clavier, activer/désactiver pour des contrôleurs spécifiques et configurer le comportement pour UITextView et les vues de saisie personnalisées. Cependant, le method swizzling peut entrer en conflit avec d’autres bibliothèques, et Apple ne recommande pas cette approche pour le code de production en raison d’effets secondaires imprévisibles.

Les alternatives incluent TPKeyboardAvoiding (une bibliothèque légère, ~2 000 étoiles) et KeyboardManager de la communauté. Pour les projets modernes, Apple recommande d’utiliser les outils intégrés d’iOS 15+, et pour les projets avec une version minimale inférieure — UIScrollView avec contentInset, qui est la solution intégrée la plus fiable.