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.

Une encoche est une zone sur certains appareils qui s'étend jusqu'à la surface d'affichage. Il offre une expérience bord à bord tout en laissant de l'espace pour d'importants capteurs à 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 accepter 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 dotés d'encoches, y compris comment utiliser la zone de découpe, c'est-à-dire le rectangle bord à bord sur la surface d'affichage qui contient l'encoche.

Image montrant un exemple d'encoche en haut au centre
Image 1. 1 Encoche.

Choisissez comment votre application gère les zones de découpe

Si vous ne souhaitez pas que votre contenu chevauche une zone d'encoche, il est généralement suffisant de vous assurer qu'il ne chevauche pas 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 sûrs et le cadre de délimitation pour chaque découpe. Ces API vous permettent de vérifier si votre contenu chevauche l'encoche afin que vous puissiez le repositionner si nécessaire.

Vous pouvez également déterminer si le contenu est positionné derrière la zone de découpe. L'attribut de mise en page 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:

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 d'encoche.

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 afin qu'aucun contenu ne s'affiche dans la zone d'encoche.

Afficher le contenu dans les zones de découpe des bords courts

Pour certains contenus, tels que les vidéos, les photos, les cartes et les jeux, l'affichage dans la zone de découpe peut être un excellent moyen de proposer aux utilisateurs une expérience bord à bord plus immersive. 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:

Image montrant le rendu du contenu dans la zone de découpe en mode Portrait
Figure 2 : Le contenu s'affiche dans la zone de découpe en mode Portrait.

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

Image montrant le rendu du contenu dans la zone de découpe en mode Paysage
Figure 3 : Le contenu s'affiche dans la zone d'encoche 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 les barres système ou non.

Une découpe dans l'angle est considérée comme faisant partie du bord court:

Image d&#39;un appareil avec une encoche d&#39;angle
Figure 4 : Appareil avec une encoche d'angle.

Ne jamais afficher de contenu dans la zone de 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:

Image montrant LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode portrait
Image 5. Exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode Portrait.

Voici un exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en mode Paysage:

Image montrant LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER pour le mode paysage
Image 6. Exemple de LAYOUT_IN_DISPLAY_CUTOUT_MODE_NEVER en mode Paysage

Bonnes pratiques pour l'encoche

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

  • Faites attention au placement des éléments critiques de l'interface utilisateur. Ne laissez pas la zone de découpe masquer le texte, les commandes ou d'autres informations importants.
  • Ne placez pas et ne étendez pas d'éléments interactifs nécessitant une reconnaissance tactile dans la zone d'encoche. La sensibilité tactile peut être plus faible dans la zone de découpe.
  • 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.

    Image montrant du contenu coupé dans la partie supérieure pour une configuration d&#39;encarts incorrecte
    Figure 7. Utilisez WindowInsetsCompat pour éviter le chevauchement ou l'arrêt de 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 d'encoche shortEdges ou never si votre application doit activer et désactiver le mode immersif. Le comportement par défaut de l'encoche peut entraîner l'affichage du contenu de votre application dans la zone d'encoche lorsque les barres système sont présentes, mais pas en mode immersif. Cela entraîne le déplacement du contenu pendant les transitions, comme illustré dans l'exemple suivant.

    Image montrant le contenu qui se déplace de haut en bas pendant les transitions.
    Figure 8. Exemple de contenu qui se déplace de haut en bas lors des transitions.
  • En mode immersif, utilisez avec précaution les coordonnées de la fenêtre plutôt que celles de l'écran, car votre application n'utilise pas la totalité de l'écran au format letterbox. En raison du format 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. Si nécessaire, vous pouvez transformer les coordonnées de l'écran en coordonnées de la vue à l'aide de getLocationOnScreen(). L'image suivante montre la différence entre les coordonnées lorsque le contenu est mis au format letterbox:

    Image montrant les coordonnées d&#39;une fenêtre par rapport à l&#39;écran lorsque le contenu est mis au format letterbox.
    Figure 9. Coordonnées de la fenêtre et de l'écran lorsque le contenu est mis au format letterbox
  • Lors de la gestion de 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 l'affichage de votre contenu

Testez tous les écrans et toutes les expériences de votre application. Effectuez des tests sur des appareils avec différents types d'encoches, si possible. Si vous n'avez pas d'appareil avec 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 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 la page jusqu'à la section Dessin et sélectionnez Simuler un écran avec une encoche.
  3. Sélectionnez le type d'encoche.

    Image montrant comment simuler une encoche dans l&#39;émulateur
    Figure 10. Options pour les développeurs permettant de tester l'affichage de votre contenu

Ressources supplémentaires