Assurer la compatibilité avec les encoches

Essayer Compose

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

Afficher les encoches dans Compose →

Une encoche est une zone de certains appareils qui s'étend jusque dans la surface d'affichage. Cela permet une expérience bord à bord tout en offrant 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) ou version ultérieure. 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 prendre en charge les appareils dotés d'une encoche, y compris la zone d'encoche, c'est-à-dire le rectangle de bord à bord sur la surface de l'écran qui contient l'encoche.

Choisissez comment votre application gère les zones d'encoche

Si vous ne souhaitez pas que votre contenu chevauche une zone d'encoche, il est généralement suffisant de veiller à ce qu'il ne chevauche pas la barre d'état ni 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 sécurisés et le cadre de délimitation de chaque encoche. Ces API vous permettent de vérifier si votre contenu chevauche l'encoche afin de pouvoir le repositionner si nécessaire.

Vous pouvez également déterminer si le contenu est disposé derrière l'encoche. 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_ALWAYS : le contenu est toujours autorisé à s'étendre dans les zones d'encoche. Il s'agit du mode par défaut pour les appareils équipés d'Android 15 ou version ultérieure.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES : le contenu s'affiche dans la zone d'encoche en mode portrait et paysage. Ne l'utilisez pas pour les fenêtres flottantes.
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER : le contenu ne s'affiche jamais dans la zone d'encoche.

Vous pouvez définir le mode d'encoche soit par programmation, soit 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

Par défaut, en mode portrait sans indicateur spécial défini, la barre d'état d'un appareil doté d'une encoche est redimensionnée pour être au moins aussi haute que l'encoche, et votre contenu s'affiche dans la zone en dessous. En mode Paysage ou plein écran, la fenêtre de votre application est mise au format letterbox pour qu'aucun contenu ne s'affiche dans la zone d'encoche.

Afficher le contenu dans les encoches des bords courts

Pour certains contenus, tels que les vidéos, les photos, les cartes et les jeux, le rendu dans la zone d'encoche peut être un excellent moyen d'offrir une expérience de bord à bord plus immersive aux utilisateurs. Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES, le contenu s'étend dans la zone d'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 chevauche 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 coin est considérée comme sur le bord court:

Ne jamais afficher de contenu dans l'encoche

Avec LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER, la fenêtre n'est jamais autorisée à 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 concernant la compatibilité avec l'encoche

Lorsque vous utilisez des encoches, tenez compte des points suivants:

• Faites attention au placement des éléments essentiels de l'interface utilisateur. Ne laissez pas la zone d'encoche masquer un texte, des commandes ou d'autres informations importants.
• Ne placez pas et n'étendez pas d'éléments interactifs nécessitant une reconnaissance tactile précise dans la zone d'encoche. La sensibilité tactile peut être inférieure 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 utilise la totalité de la fenêtre, et n'utilisez pas View.getLocationOnScreen().

• Utilisez les modes de découpe shortEdges ou never si votre application doit passer en mode immersif ou le quitter. Le comportement par défaut de l'encoche peut entraîner l'affichage du contenu de votre application dans la zone d'encoche tant que les barres système sont présentes, mais pas en mode immersif. Cela entraîne un déplacement du contenu vers le haut et vers le bas pendant les transitions, comme illustré dans l'exemple suivant.

  

• En mode immersif, soyez prudent lorsque vous utilisez des coordonnées de fenêtre ou d'écran, car votre application n'utilise pas la totalité de l'écran lorsqu'elle est au format letterbox. En raison de la boîte aux lettres, les coordonnées de l'origine de l'écran ne sont pas identiques à celles de l'origine de la fenêtre. Si nécessaire, vous pouvez convertir les coordonnées de l'écran en coordonnées de la vue à l'aide de getLocationOnScreen(). L'image suivante montre la différence de coordonnées lorsque le contenu est au format letterbox:

  

• Lorsque vous gérez MotionEvent, utilisez MotionEvent.getX() et MotionEvent.getY() pour éviter les 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 expériences de votre application. Faites des tests sur des appareils avec différents types d'encoches, si possible. Si votre appareil ne comporte pas d'encoche, vous pouvez simuler des configurations d'encoche courantes sur n'importe quel appareil ou émulateur exécutant Android 9 ou une version ultérieure. Pour ce faire, procédez comme suit:

1. Activez les Options pour les développeurs.
2. Sur l'écran Developer options (Options pour les développeurs), faites défiler la page jusqu'à la section Drawing (Dessin), puis sélectionnez Simulate a display with a cutout (Simuler un écran avec une encoche).

3. Sélectionnez le type d'encoche.

   

Ressources supplémentaires

• LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER
• LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES