Assurer la compatibilité avec les encoches

Essayer Compose

Jetpack Compose est le kit d'outils d'UI recommandé pour Android. Découvrez comment utiliser les encoches dans Compose.

Encoches dans Compose →

Une encoche est une zone qui s'étend sur la surface de l'écran de certains appareils. Il permet une expérience bord à bord tout en laissant de l'espace pour les capteurs importants à l'avant de l'appareil.

Android est compatible avec les encoches sur les appareils équipés d'Android 9 (niveau d'API 28) et versions ultérieures. Toutefois, les fabricants d'appareils peuvent également prendre en charge les encoches sur les appareils équipés d'Android 8.1 ou version antérieure.

Ce document explique comment implémenter la prise en charge des appareils avec encoches, y compris comment utiliser la zone d'encoche, c'est-à-dire le rectangle bord à bord sur la surface de l'écran qui contient l'encoche.

Choisir comment votre application gère les zones découpées

Si vous ne souhaitez pas que votre contenu se chevauche avec une zone découpée, il suffit généralement de vous assurer qu'il ne se chevauche pas avec la barre d'état et la barre de navigation. Si vous effectuez le rendu dans la zone d'encoche, utilisez WindowInsetsCompat.getDisplayCutout() pour récupérer un objet DisplayCutout contenant les encarts de sécurité et le cadre de délimitation pour chaque encoche. Ces API vous permettent de vérifier si votre contenu chevauche l'encoche afin de le repositionner si nécessaire.

Vous pouvez également déterminer si le contenu est disposé derrière la zone découpée. L'attribut de mise en page de la fenêtre layoutInDisplayCutoutMode contrôle la façon dont votre contenu est dessiné dans la zone d'encoche. Vous pouvez définir layoutInDisplayCutoutMode sur l'une des valeurs suivantes :

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT : le contenu s'affiche dans la zone de l'encoche lorsque celle-ci est contenue dans une barre système. Sinon, la fenêtre ne chevauche pas l'encoche. Par exemple, le contenu peut être mis au format letterbox lorsqu'il est affiché en mode paysage. Si votre application cible le SDK 35, cela est interprété comme ALWAYS pour les fenêtres non flottantes.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS : le contenu est toujours autorisé à s'étendre dans les zones d'encoche. Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, il s'agit du seul mode autorisé pour les fenêtres non flottantes afin d'assurer un affichage de bord à bord.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES : le contenu s'affiche dans la zone d'encoche en mode Portrait et Paysage. Ne pas utiliser pour les fenêtres flottantes. Si votre application cible le SDK 35, cela est interprété comme ALWAYS pour les fenêtres non flottantes.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER : le contenu ne s'affiche jamais dans la zone d'encoche. Si votre application cible le SDK 35, cela est interprété comme ALWAYS pour les fenêtres non flottantes.

Vous pouvez définir le mode d'encoche par programmation ou en définissant un style dans votre activité. L'exemple suivant définit un style pour appliquer l'attribut LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES à l'activité.

<style name="ActivityTheme">
  <item name="android:windowLayoutInDisplayCutoutMode">
    shortEdges <!-- default, shortEdges, or never -->
  </item>
</style>

Les sections suivantes décrivent plus en détail les différents modes de découpe.

Comportement par défaut

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS est le comportement par défaut, et LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Sinon, LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT est la valeur par défaut.

Afficher le contenu dans les zones d'encoche du bord court

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, le contenu s'étend dans la zone de l'encoche sur le bord court de l'écran, en mode Portrait et Paysage, que les barres système soient masquées ou visibles. Lorsque vous utilisez ce mode, assurez-vous qu'aucun contenu important ne se chevauche avec la zone d'encoche.

L'image suivante est un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES pour un appareil en mode Portrait :

L'image suivante est un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES pour un appareil en mode paysage :

Dans ce mode, la fenêtre s'étend sous les encoches sur le bord court de l'écran, en mode portrait et paysage, que la fenêtre masque ou non les barres système.

Une encoche dans un angle est considérée comme étant sur le bord court :

Ne jamais afficher de contenu dans la zone de l'encoche

Si votre application cible le SDK 35 et s'exécute sur un appareil Android 15, LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER est interprété comme LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS pour les fenêtres non flottantes.

Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, la fenêtre ne doit jamais chevaucher la zone d'encoche.

Voici un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en mode Portrait :

Voici un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en mode paysage :

Bonnes pratiques de compatibilité des encoches

Lorsque vous travaillez avec des encoches, tenez compte des points suivants :

• Faites attention à l'emplacement des éléments critiques de l'UI. Ne laissez pas la zone de l'encoche masquer du texte, des commandes ou d'autres informations importantes.
• Ne placez ni n'étendez aucun élément interactif nécessitant une reconnaissance tactile précise dans la zone de l'encoche. La sensibilité tactile peut être plus faible dans la zone de l'encoche.

• Dans la mesure du possible, utilisez WindowInsetsCompat pour récupérer la hauteur de la barre d'état et déterminer la marge intérieure appropriée à appliquer à votre contenu. Évitez de coder en dur la hauteur de la barre d'état, car cela peut entraîner un chevauchement ou une coupure du contenu.

  

• Utilisez View.getLocationInWindow() pour déterminer l'espace de fenêtre utilisé par votre application. Ne partez pas du principe que l'application occupe toute la fenêtre et n'utilisez pas View.getLocationOnScreen().

• Utilisez les modes d'encoche always, shortEdges ou never si votre application doit passer en mode immersif et en sortir. Le comportement par défaut de l'encoche peut entraîner l'affichage du contenu de votre application dans la zone de l'encoche lorsque les barres système sont présentes, mais pas en mode immersif. Le contenu se déplace alors vers le haut et vers le bas lors des transitions, comme le montre l'exemple suivant.

  

• En mode immersif, faites attention à l'utilisation des coordonnées de la fenêtre par rapport à celles de l'écran, car votre application n'utilise pas l'intégralité de l'écran en mode letterbox. En raison de la letterbox, les coordonnées de l'origine de l'écran ne sont pas les mêmes que celles de l'origine de la fenêtre. Vous pouvez transformer les coordonnées de l'écran en coordonnées de la vue si nécessaire à l'aide de getLocationOnScreen(). L'image suivante montre comment les coordonnées diffèrent lorsque le contenu est mis au format letterbox :

  

• Lorsque vous gérez MotionEvent, utilisez MotionEvent.getX() et MotionEvent.getY() pour éviter des problèmes de coordonnées similaires. N'utilisez pas MotionEvent.getRawX() ni MotionEvent.getRawY().

Tester le rendu de votre contenu

Testez tous les écrans et toutes les expériences de votre application. Si possible, effectuez des tests sur des appareils avec différents types d'encoches. Si vous ne disposez pas d'un appareil avec encoche, vous pouvez simuler des configurations d'encoche courantes sur n'importe quel appareil ou émulateur exécutant Android 9 ou version ultérieure en procédant comme suit :

1. Activez les options pour les développeurs.
2. Sur l'écran Options pour les développeurs, faites défiler l'écran jusqu'à la section Dessin, puis sélectionnez Simuler un écran avec encoche.

3. Sélectionnez le type de découpe.

   

Ressources supplémentaires

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_ALWAYS
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_DEFAULT